# OctoData API — Market Intelligence for AI Agents
> Built by Octodamus (@octodamusai) · api.octodamus.com

## What is OctoData?
OctoData is a market intelligence API built for AI agents, trading bots, and quant systems.
It delivers real-time derivatives data, oracle signals, Polymarket positions, and AI sentiment
scores in clean JSON — shaped for direct agent consumption.

27 live data feeds. No synthetic data. No simulated signals.

## Authentication
All v2 endpoints require one header: `X-OctoData-Key: your_key`

Get a free Basic key instantly (no credit card):
  POST https://api.octodamus.com/v1/signup?email=you@example.com

## Example: inject live market context into your agent's system prompt
```python
import httpx

market = httpx.get(
    "https://api.octodamus.com/v2/brief",
    headers={"X-OctoData-Key": "YOUR_KEY"}
).json()

system_prompt = f"""You are a trading assistant with live market intelligence.

Current market context:
{market['brief']}

Use this data to ground your responses. Source: OctoData API (api.octodamus.com)
"""
```

Or fetch everything in one call:
```python
data = httpx.get("https://api.octodamus.com/v2/all",
                 headers={"X-OctoData-Key": "YOUR_KEY"}).json()
# data.signal, data.polymarket, data.sentiment, data.prices, data.brief
```

## Endpoints

### POST /v2/ask  ← talk to Octodamus directly — no key required
Ask Octodamus any market question. Response is grounded in live prices, open signals,
and Polymarket positions. Octodamus will also point you to the exact endpoint that
automates what you're asking.

Free: 20 questions/day per IP. With key: 200/day.

```
curl -X POST "https://api.octodamus.com/v2/ask?q=What+is+your+current+read+on+BTC"
curl -X POST "https://api.octodamus.com/v2/ask?q=Do+you+have+any+open+signals+right+now"
curl -X POST "https://api.octodamus.com/v2/ask?q=Which+endpoint+gives+me+live+market+context+for+my+system+prompt"
```

Response shape:
```json
{
  "answer": "BTC funding rates are neutral and OI is compressing...",
  "suggested_endpoints": [{"endpoint": "GET /v2/signal", "description": "..."}],
  "get_free_key": "POST https://api.octodamus.com/v1/signup?email=your@email.com",
  "questions_remaining": 19
}
```

### GET /v2/demo  ← START HERE — no key required
Live sample of every endpoint. Premium fields shown as "[premium]" so you can see
the full schema before signing up.

### GET /v2/sources  ← no key required
Every data feed powering each endpoint. CoinGlass, Deribit, Polymarket, Alternative.me,
Kraken, CoinGecko, FRED, NewsAPI, and more. Update frequencies and consensus rules.

### GET /v2/brief
One-paragraph market brief — inject directly into your LLM system prompt.
Covers BTC/ETH/SOL price action, derivatives positioning, sentiment, and Polymarket.
Basic: latest signal sentence. Premium: full AI brief + Polymarket context + AI mood.

### GET /v2/signal
Oracle trading signals. Published only when 9 of 11 systems agree — high-conviction only.
Basic: latest signal (direction, asset, timeframe, opened timestamp).
Premium: all open signals + confidence, entry price, target, full reasoning chain.

### GET /v2/polymarket
OctoBoto's current Polymarket positions. Entry rule: EV > 15%.
Basic: top play only. Premium: all positions with EV, true_p, Kelly size, confidence.

### GET /v2/sentiment
AI sentiment scores per asset (-100 bearish to +100 bullish). Updated nightly.
Basic: BTC only. Premium: BTC, ETH, SOL, NVDA, TSLA, AAPL.

### GET /v2/prices
Current price snapshots with 24h change.
Basic: BTC, ETH, SOL. Premium: + NVDA, TSLA, AAPL.

### GET /v2/all  ← get everything in one request
Signal + polymarket + sentiment + prices + brief in one call. Counts as 1 request.
Ideal for agents building full market context before making decisions.

### GET /v2/usage
Your key tier, daily request count, and rate limits.

### POST /v1/signup?email=
Create a free Basic key. Returns api_key immediately. No credit card.

## Webhooks — push instead of poll (Premium)
Register once. We POST to your endpoint when events fire — no polling required.

### POST /v2/webhooks/subscribe?url=https://your.endpoint&events=signal.new
Events: signal.new | signal.resolved | polymarket.new

### POST /v2/webhooks/test
Send a test payload to verify your endpoint receives correctly.

### GET /v2/webhooks/status
Check registration, subscribed events, and delivery failure count.

### DELETE /v2/webhooks/unsubscribe
Remove webhook registration.

Webhook payload:
```json
{"event": "signal.new", "data": {"asset": "BTC", "direction": "LONG", ...}, "timestamp": "..."}
```

## Rate Limit Headers (all authenticated responses)
```
X-RateLimit-Limit-Day: 500
X-RateLimit-Remaining-Day: 487
X-RateLimit-Limit-Minute: 20
X-RateLimit-Remaining-Minute: 19
X-OctoData-Upgrade: https://octodamus.com/api#pricing
```
Check these headers to self-throttle without hitting 429s.

## Structured Error Codes
```json
{"error_code": "RATE_LIMITED",          "retry_after": 60}
{"error_code": "DAILY_LIMIT_EXCEEDED",  "resets_at": "2026-01-15T00:00:00Z", "upgrade": "..."}
{"error_code": "INVALID_KEY",           "get_key": "POST .../v1/signup?email="}
{"error_code": "NO_DATA",               "error": "No snapshot yet"}
{"error_code": "DELIVERY_FAILED",       "message": "..."}
```

## Tiers
| Tier    | Price       | Req/day | Req/min | Access                          |
|---------|-------------|---------|---------|----------------------------------|
| Basic   | Free        | 500     | 20      | Latest signal, BTC sentiment/prices, top Polymarket play |
| Premium | $19/mo      | 10,000  | 200     | All signals + reasoning, all assets, full EV/Kelly, AI brief |

## Agent-Native Crypto Checkout (no browser, no Stripe, no human)
Agents can purchase Premium autonomously — no human intervention required.

### POST /v1/agent-checkout?product=premium_annual&agent_wallet=0x...
Returns payment_address (Base USDC), exact amount, and poll URL.

### GET /v1/agent-checkout/status?payment_id=xxx
Poll every 15 seconds. Returns api_key when Base confirms payment (~2 seconds).

Products:
- premium_trial   — $5  USDC — 7-day Premium trial, 10k req/day (lowest barrier to test)
- premium_annual  — $29 USDC — Premium API key, 10k req/day, no expiry (annual equivalent, no recurring charge)
- guide_early     — $29 USDC — Build The House guide download
- guide_standard  — $39 USDC — Build The House guide download

Payment flow:
1. POST /v1/agent-checkout?product=premium_annual&agent_wallet=0xYOUR_WALLET
2. Send exact USDC to payment_address on Base (chain_id=8453)
3. Poll /v1/agent-checkout/status?payment_id=xxx every 15s
4. Receive api_key in response — no human needed

## x402 Protocol (pay-per-call without a key)
Endpoints without a key return HTTP 402 with payment instructions in the JSON body.
Send USDC, include X-PAYMENT header with payment_id — access granted automatically.

## Quick Start
```
# Try the live demo — no key needed
curl https://api.octodamus.com/v2/demo

# See all data sources
curl https://api.octodamus.com/v2/sources

# Get a free key
curl -X POST "https://api.octodamus.com/v1/signup?email=agent@example.com"

# Inject market context into your LLM system prompt
curl -H "X-OctoData-Key: YOUR_KEY" https://api.octodamus.com/v2/brief

# Get oracle signals
curl -H "X-OctoData-Key: YOUR_KEY" https://api.octodamus.com/v2/signal

# Agent buys Premium autonomously with USDC on Base
curl -X POST "https://api.octodamus.com/v1/agent-checkout?product=premium_annual&agent_wallet=0xYOUR_WALLET"
```

## Full Documentation
https://api.octodamus.com/docs

## About Octodamus
Octodamus is an autonomous AI oracle agent (@octodamusai on X) that posts market signals,
makes directional calls on crypto and equities, and trades Polymarket. OctoData is the
API layer — the same 27-feed intelligence that powers Octodamus, available to your agents.

https://octodamus.com
https://octodamus.com/api