---
name: orthogonal-surf
description: "Call Surf API through Orthogonal's pay-per-use Run API: Surf (AskSurf) crypto intelligence API: market and exchange data, on-chain data and SQL, tokens, wallets, smart money, Hyperliquid, prediction markets (Polymarket, Kalshi), US equities, news, social data, plus the Research 2.0 crypto research chat."
---

# Surf API — Orthogonal API

> Pay-per-use API on Orthogonal. Each call is billed to your Orthogonal balance.
> Base API: `https://api.orthogonal.com/v1/run` · [llms.txt](https://www.orthogonal.com/llms.txt) · [browse all APIs](https://www.orthogonal.com/catalog)

Surf (AskSurf) crypto intelligence API: market and exchange data, on-chain data and SQL, tokens, wallets, smart money, Hyperliquid, prediction markets (Polymarket, Kalshi), US equities, news, social data, plus the Research 2.0 crypto research chat.

**Verified:** no

## Access

**Run API:** `POST https://api.orthogonal.com/v1/run`
**Auth:** `Authorization: Bearer $ORTHOGONAL_API_KEY`
Get an API key at https://www.orthogonal.com/account/keys

No account or key yet? Set up Orthogonal first with https://www.orthogonal.com/skill.md: it covers the CLI, the MCP server, the TypeScript SDK and sign-up, including an agent sign-up without a password (https://www.orthogonal.com/agent-signup.md).

Every call goes through the unified Run API: send the API `slug`, the endpoint `path`, and the `query`/`body` parameters. The response is `{ "success": true, "priceCents": <US cents>, "requestId": "...", "data": { ... } }`.

Quote first, free: the same request with `"dryRun": true` returns the price without calling the API or charging anything. On a retry after a timeout, send the same `Idempotency-Key` header so the call runs and bills once.

## Endpoints

### DEX token price candles

DEX Token OHLCV Price: Returns DEX-pool-weighted OHLCV bars (timestamp, open, high, low, close, volume_usd) for a single token identified by `chain` + `address`. USD only. Bars are sorted ascending by `timestamp`.

**Use for** meme coins, newly-launched tokens, and any DEX-native asset where `/v1/market/price` returns nothing. Prefer the standard `/v1/market/price` for major listed tokens (BTC, ETH, etc.).

**Time window:** `time_range` (default `24h`) sets the window; `from`+`to` (Unix seconds or `YYYY-MM-DD`) override it. Bars use closed-interval semantics, so `24h × 1h` returns 25 bars. Maximum 1500 bars per call — combinations exceeding the cap (e.g. `30d × 5m`) return 422. `time_range=max` returns the largest allowed 1500-bar window for the selected interval.

**Identity:** `chain` (enum) + `address` (EVM hex or Solana base58). No symbol input.

`GET /gateway/v1/dex/token/price`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/80348276-612c-4b77-b9c6-1e1e1f94ff36

**Docs:** https://docs.asksurf.ai/data-api/dex/token-price

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chain` | string | Yes | Chain the token lives on. Can be `ethereum`, `base`, `bsc`, `arbitrum`, `optimism`, `polygon`, `avalanche`, or `solana`. |
| `address` | string | Yes | Token contract address — 0x-prefixed hex (42 chars) for EVM chains, base58 for Solana. NOT a ticker symbol. |
| `interval` | string | No | Candle bucket size. Sub-day intervals (`1m`-`4h`) are the typical choice for active DEX analysis. |
| `time_range` | string | No | Window of historical data to return. `max` returns the largest allowed 1500-bar window for the selected interval. Ignored when both `from` and `to` are set. |
| `from` | string | No | Start of custom date range (Unix seconds or YYYY-MM-DD). Must be set together with `to`. Overrides `time_range` when set. |
| `to` | string | No | End of custom date range (Unix seconds or YYYY-MM-DD). Must be set together with `from`. Overrides `time_range` when set. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/dex/token/price","method":"GET","query":{"chain":"<string>","address":"<string>","interval":"<string>","time_range":"<string>","from":"<string>","to":"<string>"}}'
```

### Stock balance sheet

Equity Balance Sheet: Returns paginated standardized balance-sheet periods for a US-listed equity. Each metric includes an availability status, and unavailable values are returned as null.

`GET /gateway/v1/equity/balance-sheet`

**Cost:** $0.03924 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/26b7482b-cb03-4f09-b486-ecef7d149625

**Docs:** https://docs.asksurf.ai/data-api/equity/balance-sheet

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | US equity ticker symbol |
| `period` | string | No | Financial period |
| `end_date` | string | No | Inclusive latest period end date in YYYY-MM-DD format |
| `limit` | integer | No | Maximum financial periods to return |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/balance-sheet","method":"GET","query":{"symbol":"<string>","period":"<string>","end_date":"<string>","limit":"<integer>"}}'
```

### Stock price candles

Equity Price Candles: Returns historical OHLCV candles and the latest traded price for a US-listed equity. Candles are ordered by timestamp ascending; historical data and the latest price use independent freshness windows.

`GET /gateway/v1/equity/candles`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/987f551f-e9a5-45ef-8c05-090cfa651fb2

**Docs:** https://docs.asksurf.ai/data-api/equity/candles

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | US equity ticker symbol |
| `interval` | string | No | Candle interval |
| `interval_multiplier` | integer | No | Number of intervals represented by each candle |
| `start_date` | string | No | Inclusive start date in YYYY-MM-DD format; defaults to one year before end_date |
| `end_date` | string | No | Inclusive end date in YYYY-MM-DD format; defaults to the current date in US Eastern time |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/candles","method":"GET","query":{"symbol":"<string>","interval":"<string>","interval_multiplier":"<integer>","start_date":"<string>","end_date":"<string>"}}'
```

### Stock cash flow statement

Equity Cash Flow: Returns paginated standardized cash-flow periods for a US-listed equity. With filing_accession, returns only reviewed facts for that filing and economic period. Uncovered fields are missing, and an accession with no matching facts returns an empty page. Free cash flow is standardized operating cash flow less capital expenditure paid.

`GET /gateway/v1/equity/cash-flow`

**Cost:** $0.03924 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/57d6b089-5fb7-4f94-a05b-bac7a1424cbc

**Docs:** https://docs.asksurf.ai/data-api/equity/cash-flow

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | US equity ticker symbol |
| `period` | string | No | Financial period |
| `end_date` | string | No | Inclusive latest period end date in YYYY-MM-DD format |
| `limit` | integer | No | Maximum financial periods to return |
| `filing_accession` | string | No | Exact SEC accession for the reviewed facts from one filing, including its prior-period comparative columns. Omit for the current standardized statement. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/cash-flow","method":"GET","query":{"symbol":"<string>","period":"<string>","end_date":"<string>","limit":"<integer>","filing_accession":"<string>"}}'
```

### ETF holdings

ETF Holdings: Returns a stored ETF or index-fund portfolio snapshot plus its immediately previous snapshot, ordered newest to oldest. Available quarterly periods describe the stored holdings history. The latest pair is cached for 6 hours; an explicit historical as_of pair is cached until the next calendar quarter.

`GET /gateway/v1/equity/etf/holdings`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/ab478bc2-d016-410f-ad42-2e33bd6c2289

**Docs:** https://docs.asksurf.ai/data-api/equity/etf-holdings

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | US-listed ETF or index-fund ticker symbol |
| `as_of` | string | No | Select the composition effective on or before this YYYY-MM-DD date; the response also includes its immediately previous snapshot |
| `asset_class` | string | No | Filter holdings by instrument type |
| `limit` | integer | No | Maximum holdings to return |
| `offset` | integer | No | Number of holdings to skip |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/etf/holdings","method":"GET","query":{"symbol":"<string>","as_of":"<string>","asset_class":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Stock SEC filings

Equity SEC Filings: Returns verified periodic SEC filings for a US equity, including canonical filing metadata and document URLs. Standardized statement coverage and provenance are included when available from the current equity serving publication.

`GET /gateway/v1/equity/filings`

**Cost:** Up to $0.03924 per call. Response-based: the price is worked out from the usage reported in the response, never more than $0.03924 per call. You aren't charged for failed calls. A wallet payment for a failed call is refunded.
- If you pay with a wallet (x402, MPP or Nanopayments), you pay this request's price before the call, not the final price from the response

Use `"dryRun": true` in the Run API request to see a request's price before calling.

**Page:** https://www.orthogonal.com/api/surf/58edf62a-f93b-4f46-a288-a7143415444f

**Docs:** https://docs.asksurf.ai/data-api/equity/introduction

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | US equity ticker symbol |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/filings","method":"GET","query":{"symbol":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Stock income statement

Equity Income Statement: Returns paginated standardized income-statement periods for a US-listed equity. With filing_accession, returns only reviewed facts for that filing and economic period. A matching period may have partial field coverage. Uncovered fields are missing, and an accession with no matching facts returns an empty page.

`GET /gateway/v1/equity/income-statement`

**Cost:** $0.03924 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/36afc06f-f2e1-441e-bca5-bc1e22bec5a3

**Docs:** https://docs.asksurf.ai/data-api/equity/income-statement

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | US equity ticker symbol |
| `period` | string | No | Financial period |
| `end_date` | string | No | Inclusive latest period end date in YYYY-MM-DD format |
| `limit` | integer | No | Maximum financial periods to return |
| `filing_accession` | string | No | Exact SEC accession for the reviewed facts from one filing, including its prior-period comparative columns. Omit for the current standardized statement. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/income-statement","method":"GET","query":{"symbol":"<string>","period":"<string>","end_date":"<string>","limit":"<integer>","filing_accession":"<string>"}}'
```

### Latest SEC filings

Latest Equity Filings: Returns the most recently accepted periodic SEC filings across US equities. Includes 10-K, 10-Q, 20-F, 40-F and amendments. Excludes 8-K. One filing per reporting series.

`GET /gateway/v1/equity/latest-filings`

**Cost:** Up to $0.03924 per call. Response-based: the price is worked out from the usage reported in the response, never more than $0.03924 per call. You aren't charged for failed calls. A wallet payment for a failed call is refunded.
- If you pay with a wallet (x402, MPP or Nanopayments), you pay this request's price before the call, not the final price from the response

Use `"dryRun": true` in the Run API request to see a request's price before calling.

**Page:** https://www.orthogonal.com/api/surf/5b535ac3-afd7-48b3-b92d-7f273e421e05

**Docs:** https://docs.asksurf.ai/data-api/equity/introduction

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum filings to return |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/latest-filings","method":"GET","query":{"limit":"<integer>"}}'
```

### Latest company financials

Latest Equity Financials: Returns the most recently published current-serving TTM financials across US equities. Use market_cap_min to include only companies above an explicit current-serving market capitalization threshold in USD. One company per reporting series, ranked by the current publication's SEC accepted_at then filed_on.

`GET /gateway/v1/equity/latest-financials`

**Cost:** Up to $0.03924 per call. Response-based: the price is worked out from the usage reported in the response, never more than $0.03924 per call. You aren't charged for failed calls. A wallet payment for a failed call is refunded.
- If you pay with a wallet (x402, MPP or Nanopayments), you pay this request's price before the call, not the final price from the response

Use `"dryRun": true` in the Run API request to see a request's price before calling.

**Page:** https://www.orthogonal.com/api/surf/0d66fd67-7b1e-4884-9ed6-7aafa3573b1f

**Docs:** https://docs.asksurf.ai/data-api/equity/introduction

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum companies to return |
| `market_cap_min` | number | No | Optional minimum current market capitalization in USD; omit to disable this filter |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/latest-financials","method":"GET","query":{"limit":"<integer>","market_cap_min":"<number>"}}'
```

### Stock listings

Equity Listings: Returns all current verified active stock listings for the issuer resolved from the requested ticker. Ticker alone is not treated as a durable listing identity.

`GET /gateway/v1/equity/listings`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/ab4b9829-46c9-443e-8c04-34c1a1ba3981

**Docs:** https://docs.asksurf.ai/data-api/equity/listings

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | Ticker used to resolve the issuer whose current verified stock listings are returned |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/listings","method":"GET","query":{"symbol":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Stock quick metadata

Equity Metadata: Returns lightweight identity, logo, and latest USD price metadata for one or more US-listed stocks or ETFs. Symbols are returned in request order. Company and fund identity is cached for 24 hours; prices are cached independently for 1 minute.

`GET /gateway/v1/equity/meta`

**Cost:** Up to $0.03924 per call. Response-based: the price is worked out from the usage reported in the response, never more than $0.03924 per call. You aren't charged for failed calls. A wallet payment for a failed call is refunded.
- If you pay with a wallet (x402, MPP or Nanopayments), you pay this request's price before the call, not the final price from the response

Use `"dryRun": true` in the Run API request to see a request's price before calling.

**Page:** https://www.orthogonal.com/api/surf/d666277b-f9b9-452b-a19c-9d8d72f0b0ec

**Docs:** https://docs.asksurf.ai/data-api/equity/introduction

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | One or more comma-separated US stock or ETF ticker symbols; at most 20 unique symbols |
| `include_tokenized` | boolean | No | Include tokenized counterparts of each stock — issuer-minted crypto tokens tracking the equity, with their chains and contract addresses. Off by default: most symbols have none, and the payload grows with a 20-symbol request. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/meta","method":"GET","query":{"symbol":"<string>","include_tokenized":"<boolean>"}}'
```

### Stock financial metrics

Equity Financial Metrics: Returns paginated standardized financial ratios, growth measures, per-share values, and valuation metrics for a US-listed equity.

`GET /gateway/v1/equity/metrics`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/4553661a-aa3b-4d61-9555-117b1c90cbae

**Docs:** https://docs.asksurf.ai/data-api/equity/metrics

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | US equity ticker symbol |
| `period` | string | No | Financial metric period |
| `end_date` | string | No | Inclusive latest period end date in YYYY-MM-DD format |
| `limit` | integer | No | Maximum financial periods to return |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/metrics","method":"GET","query":{"symbol":"<string>","period":"<string>","end_date":"<string>","limit":"<integer>"}}'
```

### Stock financial overview

Equity Financial Overview: Returns a paginated financial overview for a US-listed equity. Values are served as reported or derived by the financial-data serving layer; missing values remain explicit nulls and are not recalculated by this API.

`GET /gateway/v1/equity/overview`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/89bd22a0-738e-4aa9-a117-596540f639ce

**Docs:** https://docs.asksurf.ai/data-api/equity/overview

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | US equity ticker symbol |
| `period` | string | No | Financial period |
| `end_date` | string | No | Inclusive latest period end date in YYYY-MM-DD format |
| `limit` | integer | No | Maximum financial periods to return |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/overview","method":"GET","query":{"symbol":"<string>","period":"<string>","end_date":"<string>","limit":"<integer>"}}'
```

### Company profile

Equity Profile: Returns a standardized stock company profile or ETF product profile, including its business description and source-update metadata.

`GET /gateway/v1/equity/profile`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/fce64825-d973-45e2-b67d-9ccef1dffc2f

**Docs:** https://docs.asksurf.ai/data-api/equity/profile

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | US equity ticker symbol |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/profile","method":"GET","query":{"symbol":"<string>"}}'
```

### Stock segment financials

Equity Segment Financials: Returns financial facts by product, segment and other reporting dimensions. Supply filing_accession to select the presentation in a specific filing, including recast comparative figures. Compare rows within the same filing and disclosure dimension. Subtotals and consolidated totals overlap their components. For example, JPMorgan’s reported segments require segment_reconciliation rows to reach GAAP revenue. A product dimension can cover a single segment rather than the entire issuer.

`GET /gateway/v1/equity/segments`

**Cost:** $0.03924 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/d81c6614-5563-48d2-a03b-8cfd1eb538ca

**Docs:** https://docs.asksurf.ai/data-api/equity/segments

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | US equity ticker symbol |
| `period` | string | No | Financial period |
| `statement_type` | string | No | Optional statement family |
| `metric_code` | string | No | Optional normalized metric code |
| `dimension_type` | string | No | Optional provider dimension key |
| `label` | string | No | Optional provider segment label |
| `filing_accession` | string | No | Optional SEC filing accession. Selects the presentation of the requested periods in that filing, including historical recasts. Omit for current coverage. |
| `start_date` | string | No | Inclusive period start |
| `end_date` | string | No | Inclusive period end |
| `limit` | integer | No | Maximum facts to return |
| `offset` | integer | No | Number of facts to skip |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/equity/segments","method":"GET","query":{"symbol":"<string>","period":"<string>","statement_type":"<string>","metric_code":"<string>","dimension_type":"<string>","label":"<string>","filing_accession":"<string>","start_date":"<string>","end_date":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Exchange historical candles

Exchange Historical Candles: Returns persisted OHLCV candles for a covered Bithumb, Upbit, HashKey, bitFlyer, Coinone, or Korbit spot market.

**Intervals:** `5m`, `4h`, and `1w`. bitFlyer is currently reliable for weekly (`1w`) OHLCV only.

**Pagination:** use `from`/`to` to bound the time range and `limit` to cap returned candles. Results are ordered newest first.

**Synthetic candles:** `include_synthetic=true` by default, so carry-forward candles for no-trade intervals are included for continuous charts. Set `include_synthetic=false` for raw exchange-only candles. Sparse Korbit markets may rely on synthetic rows to keep charts continuous.

`GET /gateway/v1/exchange/candles`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/276bd0f5-7f12-4d17-abbd-9f79bbdf91ac

**Docs:** https://docs.asksurf.ai/data-api/exchange/candles

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | Yes | Exchange identifier |
| `pair` | string | Yes | Trading pair in base/quote form, e.g. BTC/KRW |
| `interval` | string | No | Candle interval |
| `from` | string | No | Start of time range. Accepts Unix seconds or date string |
| `to` | string | No | End of time range. Accepts Unix seconds or date string |
| `include_synthetic` | boolean | No | Whether to include carry-forward candles for no-trade intervals. Defaults to true for continuous charts; set false for raw exchange-only candles. |
| `limit` | integer | No | Max number of candles to return. Weekly candles allow up to 300 rows for a 5-year chart; intraday intervals are capped at 100. |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/exchange/candles","method":"GET","query":{"exchange":"<string>","pair":"<string>","interval":"<string>","from":"<string>","to":"<string>","include_synthetic":"<boolean>","limit":"<integer>","offset":"<integer>"}}'
```

### Exchange market coverage

Exchange Market Coverage: Returns covered spot markets on Bithumb, Upbit, HashKey, bitFlyer, Coinone, and Korbit with latest ticker metrics, candle availability, technical score, and data status.

**Ticker fields:** latest price, 24h open/high/low, previous close, signed 24h price and percent change, and 24h base/quote volume when the exchange provides them.

Use the returned `pair` values with `/exchange/candles` for historical OHLCV.

**Coverage notes:** bitFlyer coverage is currently strongest for weekly (`1w`) OHLCV. Korbit markets can have sparse intraday rows during no-trade periods; inspect `data_status` and `data_actionability` before using a market.

`GET /gateway/v1/exchange/coverage`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/4870c3fc-2661-4b0c-883d-da27c39c9c70

**Docs:** https://docs.asksurf.ai/data-api/exchange/coverage

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Exchange identifier. When omitted, returns all supported exchanges. |
| `q` | string | No | Free-text search over pair, base currency, or quote currency |
| `quote` | string | No | Quote currency filter |
| `type` | string | No | Market type |
| `status` | string | No | Market status filter |
| `data_status` | string | No | Market data coverage status filter |
| `sort_by` | string | No | Sort field |
| `order` | string | No | Sort order |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/exchange/coverage","method":"GET","query":{"exchange":"<string>","q":"<string>","quote":"<string>","type":"<string>","status":"<string>","data_status":"<string>","sort_by":"<string>","order":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Order book depth

Exchange Order Book Depth: Returns order book bid/ask levels with computed stats.

**Included fields:** spread, spread percentage, mid-price, and total bid/ask depth.

Use `limit` to control the number of price levels (1–100, default 20). Set `type=swap` to query perpetual contract order books instead of spot.

`GET /gateway/v1/exchange/depth`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/0d15ccb6-c92a-4319-be60-635f2fb53fad

**Docs:** https://docs.asksurf.ai/data-api/exchange/depth

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pair` | string | Yes | Trading pair (e.g. BTC/USDT) |
| `type` | string | No | Market type: spot for spot trading, swap/perpetual/perp for perpetual contracts |
| `limit` | integer | No | Number of price levels (1-100) |
| `exchange` | string | No | Exchange identifier. Note: hyperliquid uses USDC-settled perps (e.g. BTC/USDC:USDC); pass USDC-quoted pairs when querying hyperliquid. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/exchange/depth","method":"GET","query":{"pair":"<string>","type":"<string>","limit":"<integer>","exchange":"<string>"}}'
```

### Funding rate history

Exchange Funding Rate History: Returns historical funding rate records for a perpetual contract.

**Pagination:** use `from` to set the start time and `limit` to control result count. For longer history, pass the last returned timestamp as the next `from` value.

**Note:** not all exchanges support historical queries via `from`; some only return recent data regardless.

For the latest funding rate snapshot, see `/exchange/perp?fields=funding`.

`GET /gateway/v1/exchange/funding-history`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/3310da56-e4ad-4bdb-b459-c6b017c2e9c4

**Docs:** https://docs.asksurf.ai/data-api/exchange/funding-history

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pair` | string | Yes | Trading pair (e.g. BTC/USDT) |
| `from` | string | No | Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD, ISO8601). Not all exchanges support historical queries; some only return recent data regardless of this value. |
| `limit` | integer | No | Max number of records. For longer history, paginate using the last returned timestamp as the next from value. |
| `exchange` | string | No | Exchange identifier. Note: hyperliquid uses USDC-settled perps (e.g. BTC/USDC:USDC); pass USDC-quoted pairs when querying hyperliquid. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/exchange/funding-history","method":"GET","query":{"pair":"<string>","from":"<string>","limit":"<integer>","exchange":"<string>"}}'
```

### Exchange OHLCV candles

Exchange OHLCV Candlesticks: Returns OHLCV candlestick data with period summary stats (high, low, total volume).

**Intervals:** 15 options from `1m` to `1M`.

**Pagination:** use `from` to set the start time and `limit` to control candle count. For longer ranges, pass the last returned candle's timestamp as the next `from` value. Exchange-side limits vary (200–1000 per request).

Set `type=swap` to query perpetual contract candles instead of spot.

`GET /gateway/v1/exchange/klines`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/4a5e322c-5004-4e5d-b510-48af851ef765

**Docs:** https://docs.asksurf.ai/data-api/exchange/klines

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pair` | string | Yes | Trading pair (e.g. BTC/USDT) |
| `type` | string | No | Market type: spot for spot trading, swap/perpetual/perp for perpetual contracts |
| `interval` | string | No | Candle size — bucket duration for each returned OHLCV row. This endpoint uses `interval` only; it does NOT accept `time_range`. Use `from` + `limit` to control the window. |
| `from` | string | No | Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD, ISO8601) |
| `limit` | integer | No | Max number of candles to return. Exchange may cap lower (e.g. 200-1000). For longer ranges, paginate using the last returned timestamp as the next from value. |
| `exchange` | string | No | Exchange identifier. Note: hyperliquid uses USDC-settled perps (e.g. BTC/USDC:USDC); pass USDC-quoted pairs when querying hyperliquid. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/exchange/klines","method":"GET","query":{"pair":"<string>","type":"<string>","interval":"<string>","from":"<string>","limit":"<integer>","exchange":"<string>"}}'
```

### Long/short ratio history

Exchange Long/Short Ratio History: Returns historical long/short ratio for a perpetual contract.

**Included fields:** ratio value, long account percentage, short account percentage.

**Granularity:** `interval` supports `1h`, `4h`, `1d`.

**Pagination:** use `from` for start time and `limit` for result count. For longer history, pass the last returned timestamp as the next `from` value.

**Note:** not all exchanges support historical queries via `from`; some only return recent data regardless.

Just pass the base pair (e.g. `pair=BTC/USDT`). For aggregated cross-exchange long/short ratio, see `/market/futures`.

`GET /gateway/v1/exchange/long-short-ratio`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/7b6fc2c0-baf5-46e7-970b-cee2fe1d581a

**Docs:** https://docs.asksurf.ai/data-api/exchange/long-short-ratio

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pair` | string | Yes | Trading pair (e.g. BTC/USDT) |
| `interval` | string | No | Bucket size for each point in the series: `1h`, `4h`, or `1d`. This endpoint uses `interval` only; it does NOT accept `time_range`. Use `from` + `limit` to control the window. |
| `from` | string | No | Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD, ISO8601). Binance only retains the last 30 days of data; other exchanges may have different limits. |
| `limit` | integer | No | Max number of records. For longer history, paginate using the last returned timestamp as the next from value. |
| `exchange` | string | No | Exchange identifier |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/exchange/long-short-ratio","method":"GET","query":{"pair":"<string>","interval":"<string>","from":"<string>","limit":"<integer>","exchange":"<string>"}}'
```

### Exchange trading pairs

Exchange Trading Pairs: Returns trading pairs available on an exchange.

**Default exchange:** `binance` when `exchange` is omitted.

**Filters:** `type` (`spot`, `swap`, `future`, `option`) or free-text `search`.

**Included fields:** pair name, base/quote currencies, market type, active status, and default fee rates.

Use the returned `pair` values as the `pair` parameter in other exchange endpoints.

`GET /gateway/v1/exchange/markets`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/92ff3348-5afc-4de4-b686-ae4300c43367

**Docs:** https://docs.asksurf.ai/data-api/exchange/markets

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Exchange identifier. Defaults to binance. Pass a specific venue to list that exchange only. |
| `type` | string | No | Market type filter. Use perpetual or perp for perpetual contracts (alias for swap). |
| `base` | string | No | Filter by base currency |
| `quote` | string | No | Filter by quote currency |
| `search` | string | No | Fuzzy search in pair/base/quote |
| `limit` | integer | No | Max results |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/exchange/markets","method":"GET","query":{"exchange":"<string>","type":"<string>","base":"<string>","quote":"<string>","search":"<string>","limit":"<integer>"}}'
```

### Perpetual contract snapshot

Exchange Perpetual Contract Snapshot: Returns a perpetual futures snapshot for a trading pair: funding rate, open interest, mark/index price.

**Available fields** (via `fields`):
- `funding` — current funding rate, next settlement, mark/index price
- `oi` — open interest in contracts and USD

Just pass the base pair (e.g. `pair=BTC/USDT`). The swap settle suffix is added automatically from the quote currency, e.g. `BTC/USDT:USDT` or `BTC/USDC:USDC`.

`GET /gateway/v1/exchange/perp`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/15dd6251-42b0-43bc-a1d6-cbb1f2818963

**Docs:** https://docs.asksurf.ai/data-api/exchange/perp

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pair` | string | Yes | Trading pair (e.g. BTC/USDT). The swap settle suffix is added automatically from the quote currency, e.g. BTC/USDT:USDT or BTC/USDC:USDC. |
| `fields` | string | No | Comma-separated fields to include: 'funding' (current funding rate), 'oi' (open interest). Defaults to all fields. |
| `exchange` | string | No | Exchange identifier. Hyperliquid uses USDC-settled perps (e.g. BTC/USDC:USDC). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/exchange/perp","method":"GET","query":{"pair":"<string>","fields":"<string>","exchange":"<string>"}}'
```

### Exchange ticker price

Exchange Ticker Price: Returns the real-time ticker for a trading pair.

**Included fields:** last price, bid/ask, 24h high/low, 24h volume, 24h price change.

Set `type=swap` to query perpetual contract prices instead of spot. For historical price trends, use `/market/price`.

`GET /gateway/v1/exchange/price`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/5bb55303-fc69-4dcf-bdf0-0f3fa88da6af

**Docs:** https://docs.asksurf.ai/data-api/exchange/price

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pair` | string | Yes | Trading pair (e.g. BTC/USDT) |
| `type` | string | No | Market type: spot for spot trading, swap/perpetual/perp for perpetual contracts |
| `exchange` | string | No | Exchange identifier. Note: hyperliquid uses USDC-settled perps (e.g. BTC/USDC:USDC); pass USDC-quoted pairs when querying hyperliquid. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/exchange/price","method":"GET","query":{"pair":"<string>","type":"<string>","exchange":"<string>"}}'
```

### Crypto fund profile

Fund Profile Detail: Returns a crypto VC fund's full profile: description, jurisdiction, portfolio count, social links, and team members with roles.

**Included fields:** X accounts, team members, recent research, invested project count.

This does NOT return the list of investments — use `/fund/portfolio` for that.

**Lookup:** by UUID (`id`) or name (`q`). Returns 404 if not found.

`GET /gateway/v1/fund/detail`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/e1d2326b-d40e-4898-93a1-501e7b2e9105

**Docs:** https://docs.asksurf.ai/data-api/fund/detail

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Surf fund UUID. PREFERRED — always use this when available from a previous response (e.g. id from /search/fund). Takes priority over q. |
| `q` | string | No | Fuzzy fund name search. Only use when 'id' is not available. May return unexpected results for ambiguous names. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/fund/detail","method":"GET","query":{"id":"<string>","q":"<string>"}}'
```

### Crypto fund portfolio

Fund Portfolio: Returns investment rounds for a fund's portfolio, sorted by date (newest first).

A project may appear multiple times if the fund participated in multiple rounds.

**Included fields:** project name, logo, date, raise amount, lead investor status.

**Lookup:** by UUID (`id`) or name (`q`).

`GET /gateway/v1/fund/portfolio`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/e55ffbc3-6c8d-4723-a7cf-479e7d15eb54

**Docs:** https://docs.asksurf.ai/data-api/fund/portfolio

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Surf fund UUID. PREFERRED — always use this when available from a previous response (e.g. id from /search/fund). Takes priority over q. |
| `q` | string | No | Fuzzy fund name search. Only use when 'id' is not available. May return unexpected results for ambiguous names. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |
| `is_lead` | string | No | Filter by lead investor status. Omit or leave empty for all investments. |
| `invested_after` | integer | No | Only include investments at or after this Unix timestamp (seconds) |
| `invested_before` | integer | No | Only include investments before this Unix timestamp (seconds) |
| `sort_by` | string | No | Field to sort results by |
| `order` | string | No | Sort order |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/fund/portfolio","method":"GET","query":{"id":"<string>","q":"<string>","limit":"<integer>","offset":"<integer>","is_lead":"<string>","invested_after":"<integer>","invested_before":"<integer>","sort_by":"<string>","order":"<string>"}}'
```

### Crypto fund ranking

Fund Ranking: Returns top crypto VC funds ranked by tier or portfolio count.

**Available metrics:** `tier` (lower is better), `portfolio_count` (number of invested projects).

`GET /gateway/v1/fund/ranking`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/aeb46dcc-8d8d-45d2-a8ee-2f682d580ab6

**Docs:** https://docs.asksurf.ai/data-api/fund/ranking

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `metric` | string | Yes | Ranking metric. Can be `tier` (lower is better) or `portfolio_count` (number of invested projects). |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/fund/ranking","method":"GET","query":{"metric":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Token signal detail

Signal Detail: Returns one project signal card.

**Lookup:** pass exactly one of `id` (Surf token UUID) or `project_slug`. Use `time_range` (`24h` or `7d`) to select the score window.

`GET /gateway/v1/heatscore/detail`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/58d20623-34d4-4f8c-9bc0-de6693f96c31

**Docs:** https://docs.asksurf.ai/data-api/signal/detail

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Surf token UUID. Pass exactly one of id or project_slug. |
| `project_slug` | string | No | Project slug. Pass exactly one of id or project_slug. |
| `time_range` | string | No | Window to compute signal score over: 24h or 7d. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/heatscore/detail","method":"GET","query":{"id":"<string>","project_slug":"<string>","time_range":"<string>"}}'
```

### Signal project list

Signal Projects: Returns a paginated ranked snapshot of project signal cards.

**Included fields:** project identity, score, latest price, price-change percentages, core state, dimension scores, compact token signals, AI summaries, and supporting market metrics.

**Filters:** `time_range` (`24h` or `7d`). Supports `limit`/`offset` pagination.

`GET /gateway/v1/heatscore/projects`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/33e46d19-389a-4fe6-9a3d-f373511e984c

**Docs:** https://docs.asksurf.ai/data-api/signal/projects

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `time_range` | string | No | Window to compute signal scores over: 24h or 7d. Returns a ranked snapshot, not a time-series. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/heatscore/projects","method":"GET","query":{"time_range":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Token of the day

Signal Token Of The Day: Returns the token-of-the-day project signal cards with latest price, price-change percentages, dimension scores, compact signals, and AI summaries. Supports `limit`/`offset` pagination.

`GET /gateway/v1/heatscore/token-of-the-day`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/2b3247eb-c002-4c63-b3de-3a966d5d49d4

**Docs:** https://docs.asksurf.ai/data-api/signal/token-of-the-day

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/heatscore/token-of-the-day","method":"GET","query":{"limit":"<integer>","offset":"<integer>"}}'
```

### Token of the week

Signal Token Of The Week: Returns the token-of-week project signal cards with latest price, price-change percentages, dimension scores, compact signals, and AI summaries. Supports `limit`/`offset` pagination.

`GET /gateway/v1/heatscore/token-of-week`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/2856b308-ad50-40e7-8eb2-9119f7e76b06

**Docs:** https://docs.asksurf.ai/data-api/signal/token-of-week

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/heatscore/token-of-week","method":"GET","query":{"limit":"<integer>","offset":"<integer>"}}'
```

### Hyperliquid account value

Account Portfolio: Returns a wallet's full portfolio across perps, spot, vaults, and staking in one call, with a perp+vault equity roll-up (`total_value_usd` is the total-equity figure a dashboard header should show, vs the perp-only equity on `/performance` and `/positions`). This is the source for spot balances.

This is a point-in-time snapshot, not a time series; its perp block duplicates the margin summary from `/hyperliquid/positions` (this endpoint adds spot/vault/staking so it stands alone as a full-portfolio call). Sections are fetched independently: if one fails, that section is omitted (not null) and the failure is named in `errors[]`. The call returns 200 when at least one section succeeds, and 502 only if all four fail. Spot balances are token-denominated and staking is in HYPE.

`GET /gateway/v1/hyperliquid/account`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/eb5ca846-9189-4a8d-ad46-4d37a7d5afb0

**Docs:** https://docs.asksurf.ai/data-api/hyperliquid/account

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address: a 0x EVM address or an ENS name (e.g. vitalik.eth). Solana addresses are not supported. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/hyperliquid/account","method":"GET","query":{"address":"<string>"}}'
```

### Hyperliquid market candles

Market Candles: Returns market OHLCV candles for charting and trade-review overlays, ordered by open_time ascending. Each row also carries trades, closed, and nullable quote volume (null before quote-volume coverage). symbol, from, and to are required; from/to accept Unix seconds, ISO datetimes, or UTC dates, and candle open_time is bounded to the half-open [from,to) window. The requested window may contain at most 5000 candles, so use a larger interval for long histories. The response is market data and does not require a wallet address.

`GET /gateway/v1/hyperliquid/candles`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/adb86dda-c86d-4f86-98f6-18ecb0c0d336

**Docs:** https://docs.asksurf.ai/data-api/hyperliquid/candles

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | Hyperliquid market id (for example BTC, kPEPE, xyz:GOLD, the canonical PURR/USDC spot pair, or an @index spot market). |
| `interval` | string | No | Candle granularity. |
| `from` | string | Yes | Window start (Unix seconds, an ISO datetime, or a bare UTC date). |
| `to` | string | Yes | Window end (Unix seconds, an ISO datetime, or a bare UTC date; a bare date means the end of that day). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/hyperliquid/candles","method":"GET","query":{"symbol":"<string>","interval":"<string>","from":"<string>","to":"<string>"}}'
```

### Hyperliquid trade fills

Fills: Returns a wallet's individual fills (fill-level executions), newest first by default, with realized PnL, fees, and direction (`crossed`=true marks a taker fill that took liquidity). For closed round-trip trades (one row per open→close position, with per-trade P&L incl. funding), use `/hyperliquid/trades` instead — funding is NOT attributable at fill level.

Default `order=desc` is a recent-capped window (no `offset`): up to `limit` of the most-recent fills; page back by setting `to` to the oldest `time` you received (or `to_ms`+`to_fill_id` for millisecond-exact paging). For COMPLETE history with no cap, use `order=asc` with `from` and follow `meta.next_cursor`. `symbol` filters to one market (applied client-side, so with `order=desc` it only filters the recent window — pair with `from`/`to` to reach older history).

`GET /gateway/v1/hyperliquid/fills`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/a0f2833e-7771-43b3-a144-511fd600ff97

**Docs:** https://docs.asksurf.ai/data-api/hyperliquid/fills

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address: a 0x EVM address or an ENS name (e.g. vitalik.eth). Solana addresses are not supported. |
| `from` | string | No | Window start (Unix seconds or a date). With the default order=desc, results cover the window forward from this point and are capped at ~2000 of the earliest fills in range (narrow the range to see the most-recent fills). With order=asc this is the start of a complete-history walk: follow meta.next_cursor to page through every fill in the window with no cap. |
| `to` | string | No | Window end (Unix seconds or a date), inclusive. Defaults to now. With order=desc, page back within the most-recent results by setting this to the oldest time you received (prefer to_ms for millisecond precision); with order=asc it bounds the walk. |
| `to_ms` | integer | No | Window end in Unix milliseconds, for millisecond-precise desc paging: pass the time_ms of the oldest fill you received to fetch the next page. On its own the boundary is exclusive (fills AT to_ms are dropped), so when more than limit fills share one millisecond the remainder is skipped — pair it with to_fill_id to page losslessly through a boundary millisecond. Takes precedence over to (which is ignored when to_ms is set). Like to, it pages within the recent (~2000-fill) window. desc-only: rejec |
| `to_fill_id` | string | No | Cursor tiebreak for to_ms: pass the fill_id of the oldest fill you received alongside its time_ms as to_ms. The next page then resumes strictly after that (time_ms, fill_id) pair — fills at the boundary millisecond with a lower fill_id are included instead of skipped, so paging never loses fills that share a millisecond. Requires to_ms; desc-only. Equivalent to following meta.next_cursor, which encodes the same position. An empty page can mean the window is exhausted (set from to reach older his |
| `order` | string | No | desc (default): newest first — the recent feed, or the earliest-anchored ~2000-fill slice when from is set. asc: oldest first, a complete-history walk from from (required) up to to — each page links the next via meta.next_cursor with no result cap, the reliable mode for full trade-history or PnL reconstruction. |
| `cursor` | string | No | Opaque continuation token from a previous response's meta.next_cursor. It encodes the paging direction, position, and window, so pass it with only symbol and limit — combining it with from, to, to_ms, or to_fill_id is rejected with 400. |
| `symbol` | string | No | Filter to one market (exact match, e.g. xyz:GOLD). Applied client-side: with order=desc it filters after the recent cap (pair it with from/to so older fills are not missed); with order=asc the cursor walk scans past non-matching fills, so a page may return fewer than limit items (or none) while meta.next_cursor still advances. |
| `limit` | integer | No | Page size (1-100). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/hyperliquid/fills","method":"GET","query":{"address":"<string>","from":"<string>","to":"<string>","to_ms":"<integer>","to_fill_id":"<string>","order":"<string>","cursor":"<string>","symbol":"<string>","limit":"<integer>"}}'
```

### Hyperliquid trader leaderboard

Trader Leaderboard: Returns traders ranked by a chosen performance metric (PnL by default), with quality filters to exclude bots and brand-new accounts. Each row carries `rank` (1-based, offset-adjusted position in this response's ordering).

**Metric basis — does NOT reconcile with `/performance`:** the leaderboard is built on the upstream Hydromancer trade model, whose `total_pnl` is funding-INCLUSIVE over an all-markets trade universe, while `/hyperliquid/performance`/`/trades`/`/trades/aggregate` are funding-EXCLUDED over our episode warehouse. A leaderboard PnL and the same trader's `/performance` net can differ severalfold — do not display them side-by-side as the same number.

**Ranking:** `sort_by` (`total_pnl`, `win_rate`, `volume_traded`) over a `time_range` window (`1d`, `7d`, `30d`, `90d`, `all`). Always sorted descending.

**Filters:** `min_trades` (defaults to 5; pass `0` for the full population), `min_days_active`, `min_account_age_days`, `min_human_score`, and `dex` (`m

`GET /gateway/v1/hyperliquid/leaderboard`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/155014c9-c317-4c29-8c0f-6db8e7878103

**Docs:** https://docs.asksurf.ai/data-api/hyperliquid/leaderboard

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `time_range` | string | No | Window to rank over. Default all (data starts 2025-08-01). |
| `sort_by` | string | No | Rank by this metric. Always sorted descending. |
| `min_trades` | integer | No | Only traders with at least this many trades. Defaults to 5; pass 0 for the full population. |
| `min_days_active` | integer | No | Only traders active at least this many days (0 = no filter). |
| `min_account_age_days` | integer | No | Only accounts at least this old, in days (0 = no filter). |
| `min_human_score` | integer | No | Only traders scoring at least this, 0-100 (0 = no filter). |
| `dex` | string | No | Market to rank within: main_dex (or omit) for the native market ONLY, or a builder market — one of: xyz, flx, vntl, hyna, km, abcd, cash, para, mkts. NOTE: the omit default differs from /trades/aggregate, where omitting dex aggregates across ALL markets. |
| `limit` | integer | No | Results per page (1-100). |
| `offset` | integer | No | Results to skip. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/hyperliquid/leaderboard","method":"GET","query":{"time_range":"<string>","sort_by":"<string>","min_trades":"<integer>","min_days_active":"<integer>","min_account_age_days":"<integer>","min_human_score":"<integer>","dex":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Hyperliquid wallet orders

Open & Recent Orders: Returns a wallet's live resting orders (`open` — stops, take-profits, limits, with trigger type) plus its recent terminal orders (`historical` — filled / canceled / rejected). Use `open` for "is a stop set right now?" and `historical` for the set-then-cancelled timeline. Order `side` is in trade terms (`buy`/`sell`), not position terms — a sell stop protects a long; join to `/hyperliquid/positions` by `symbol`.

Sections are truncated to `open_limit` (default 500) / `historical_limit` (default 200) — `open_total`/`historical_total` carry the pre-truncation counts. Both sections mix PERP and SPOT orders — check `market_type`: spot orders carry raw spot-pair-index symbols (`@107`) that never join to `/positions`, `/trades`, or `/fills` (perp-only surfaces); filter `market_type=perp` for a perp working-orders panel.

`historical` is **one row per order at its final status**, newest first: the upstream feed is a status-transition stream (an order appears as `open`, th

`GET /gateway/v1/hyperliquid/orders`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/5cb5a87a-334d-4dd1-8b35-50241618fca2

**Docs:** https://docs.asksurf.ai/data-api/hyperliquid/orders

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address: a 0x EVM address or an ENS name (e.g. vitalik.eth). Solana addresses are not supported. |
| `open_limit` | integer | No | Max open orders returned (market makers can hold 1500+; open_total reports the pre-truncation count). |
| `historical_limit` | integer | No | Max terminal orders returned, newest first (the upstream feed holds ~1000 post-collapse; historical_total reports the pre-truncation count). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/hyperliquid/orders","method":"GET","query":{"address":"<string>","open_limit":"<integer>","historical_limit":"<integer>"}}'
```

### Hyperliquid trading performance

Trading Performance: Returns the connected user's lifetime trading-performance summary — the dashboard header: re-rolled realized performance (win rate, profit factor, gross/net PnL — **funding-excluded**, net = gross − fees), the live position snapshot, and account value.

This is a lifetime, point-in-time summary: it takes NO `from`/`to` window (use `/hyperliquid/trades` for windowed, paginated closed trades) and carries NO trade list. `account_value` is the live **perp clearinghouse** equity only — NOT total portfolio; for total equity incl. spot/vault use `/hyperliquid/account` (`total_value_usd`). Sections degrade independently: a failed section is named in `errors[]` and the call still returns 200. A genuinely flat perp account returns `account_value` 0 with no `errors[]`; the field is omitted only when the snapshot section degraded (which also adds an `errors[]` entry) — so detect degradation via `errors[]`, not a 0 value.

`GET /gateway/v1/hyperliquid/performance`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/f730ea52-0d95-45d4-bf00-b26d6439687a

**Docs:** https://docs.asksurf.ai/data-api/hyperliquid/performance

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address: a 0x EVM address or an ENS name (e.g. vitalik.eth). Solana addresses are not supported. |
| `dex` | string | No | NOT SUPPORTED on /performance — returns 400 if set. The lifetime summary always spans ALL markets; market scoping lives on /trades/aggregate (dex=...). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/hyperliquid/performance","method":"GET","query":{"address":"<string>","dex":"<string>"}}'
```

### Hyperliquid open positions

Open Positions: Returns a wallet's open perpetual positions with its cross-margin summary and derived risk (leverage, unrealized PnL, ROE, liquidation price, margin ratio, distance-to-liquidation).

`liquidation_price` (and `distance_to_liquidation`) can be null even on a leveraged position — Hyperliquid returns none for cross positions whose spot collateral backstops them; in that case use the account-level `margin_ratio` (the account liquidates as it approaches 1.0) for proximity. `account_value` here is perp clearinghouse equity, not total portfolio (see `/hyperliquid/account`). Positions are sorted by position value (largest first). `dex` scopes to a builder market; omit (or `main_dex`) for the native market.

`GET /gateway/v1/hyperliquid/positions`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/1e6ac541-c9cb-4ba8-9684-5369df2c369c

**Docs:** https://docs.asksurf.ai/data-api/hyperliquid/positions

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address: a 0x EVM address or an ENS name (e.g. vitalik.eth). Solana addresses are not supported. |
| `dex` | string | No | Market scope: omit (or main_dex) for the native market, or a builder market — one of: xyz, flx, vntl, hyna, km, abcd, cash, para, mkts. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/hyperliquid/positions","method":"GET","query":{"address":"<string>","dex":"<string>"}}'
```

### Hyperliquid closed trades

Closed Trades: Returns a wallet's closed round-trip trades — one row per open→close position lifecycle, with realized per-trade P&L (gross, net = gross − fees, fees, and `funding_pnl` as a **separate** field that net EXCLUDES), entry/exit price, size, and hold time. Newest close first. This is the journal / calendar / attribution source; for fill-level executions use `/hyperliquid/fills` instead.

Returns EVERY closed trade in the window — it does NOT filter by symbol or direction (a `symbol`/`direction` query param is ignored, not applied); for per-symbol / per-direction rollups use `/hyperliquid/trades/aggregate`, or `/hyperliquid/fills` for symbol-scoped fills. `funding_pnl` is 0 for warehouse rows and populated only on the live tail, so a funding-inclusive total is incomplete before the watermark.

Cursor-paged over the full history (warehouse + a live gap-fill for the most recent days): follow `meta.next_cursor` to page back. The cursor is a complete continuation token (it encodes

`GET /gateway/v1/hyperliquid/trades`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/28d9d143-0507-4576-9485-2c9037221691

**Docs:** https://docs.asksurf.ai/data-api/hyperliquid/trades

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address: a 0x EVM address or an ENS name (e.g. vitalik.eth). Solana addresses are not supported. |
| `symbol` | string | No | NOT SUPPORTED on /trades — returns 400 if set. Per-symbol slicing lives on /trades/aggregate (group_by=symbol) or client-side. |
| `direction` | string | No | NOT SUPPORTED on /trades — returns 400 if set. Per-direction slicing lives on /trades/aggregate (group_by=direction) or client-side. |
| `dex` | string | No | NOT SUPPORTED on /trades — returns 400 if set. Market scoping lives on /trades/aggregate (dex=...). |
| `from` | string | No | Window start: Unix seconds, an ISO datetime (2026-03-01T12:00:00Z), or a bare date (= midnight UTC). Omit for the full history. |
| `to` | string | No | Window end, inclusive: Unix seconds, an ISO datetime, or a bare date — a bare date means the END of that UTC day, so from=X&to=X covers the whole day X. Defaults to now. |
| `cursor` | string | No | Opaque continuation token from a previous response's meta.next_cursor. It encodes the window, position, and address, so pass it with only address + limit — and only with the address it was issued for. Tokens are single-use opaque values: identical requests mint different tokens that decode to the same position. |
| `limit` | integer | No | Page size (1-100). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/hyperliquid/trades","method":"GET","query":{"address":"<string>","symbol":"<string>","direction":"<string>","dex":"<string>","from":"<string>","to":"<string>","cursor":"<string>","limit":"<integer>"}}'
```

### Hyperliquid trade aggregates

Closed Trades Aggregate: Returns a wallet's closed trades rolled up server-side into one row per group — so the P&L calendar, per-symbol / direction / size attribution, and the realized equity curve are one call each instead of paging the whole trade history.

**`group_by`:** `day` (UTC calendar day — the calendar and equity-curve source), `symbol` (per market), `direction` (long vs short), `size_bucket` (notional-USD tiers: `<1k`, `1k-10k`, `10k-100k`, `100k-1m`, `1m+`), or `hold_bucket` (holding-time tiers: `<5m`, `5m-1h`, `1h-1d`, `1d-1w`, `1w+`). Tiers with no trades are omitted — render the full ladder client-side and zero-fill. One dimension per call.

**Per group:** trade_count, gross_pnl, net_pnl (funding-excluded — gross − fees, matching `/trades` and `/performance`), fees, funding_pnl (live tail only), win_rate, volume_usd (notional), avg_win, avg_loss.

`from`/`to` (Unix seconds or a date) bound close_time; omit for full history. Totals reconcile to `/trades` and `/performan

`GET /gateway/v1/hyperliquid/trades/aggregate`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/4511fa1b-ec35-4d51-89be-81685c889049

**Docs:** https://docs.asksurf.ai/data-api/hyperliquid/trades-aggregate

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address: a 0x EVM address or an ENS name (e.g. vitalik.eth). Solana addresses are not supported. |
| `group_by` | string | No | Dimension to roll up by. day = UTC calendar day (the P&L calendar / equity-curve source); symbol = per market; direction = long vs short; size_bucket = notional-USD tiers; hold_bucket = holding-time tiers. |
| `from` | string | No | Window start, bounds close_time: Unix seconds, an ISO datetime (2026-03-01T12:00:00Z), or a bare date (= midnight UTC). Omit for full history. |
| `to` | string | No | Window end, inclusive, bounds close_time: Unix seconds, an ISO datetime, or a bare date — a bare date means the END of that UTC day, so from=X&to=X covers the whole day X. Defaults to now. |
| `dex` | string | No | Market scope: main_dex for the native market only, omit to aggregate across ALL markets, or a builder market — one of: xyz, flx, vntl, hyna, km, abcd, cash, para, mkts. NOTE: the omit default differs from /leaderboard, where omitting dex means the native market only. |
| `fill_gaps` | boolean | No | group_by=day only: emit a zero row for every no-trade UTC day in the window so the calendar is dense. Requires from (a bounded window); ignored for other group_by values. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/hyperliquid/trades/aggregate","method":"GET","query":{"address":"<string>","group_by":"<string>","from":"<string>","to":"<string>","dex":"<string>","fill_gaps":"<boolean>"}}'
```

### Hyperliquid trade funding context

Closed Trade Funding and Leverage: Returns immutable funding and leverage context for one closed trade identified by the composite key from `/hyperliquid/trades`. Use this for a selected trade detail instead of enriching every history row. `funding_status=complete` distinguishes a real zero from unavailable historical data; leverage fields are omitted when the completed-trade source has no value.

`GET /gateway/v1/hyperliquid/trades/context`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/4d6b9606-17dd-4b60-8f56-03ea8dcfe128

**Docs:** https://docs.asksurf.ai/data-api/hyperliquid/trade-context

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address: a 0x EVM address or an ENS name (e.g. vitalik.eth). Solana addresses are not supported. |
| `symbol` | string | Yes | Hyperliquid perpetual market id, including a builder prefix for HIP-3 markets (for example xyz:GOLD). |
| `direction` | string | Yes | Opening direction of the episode. |
| `open_time` | integer | Yes | Episode open time, Unix seconds, copied from GET /hyperliquid/trades. |
| `close_time` | integer | Yes | Episode close time, Unix seconds, copied from GET /hyperliquid/trades. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/hyperliquid/trades/context","method":"GET","query":{"address":"<string>","symbol":"<string>","direction":"<string>","open_time":"<integer>","close_time":"<integer>"}}'
```

### Crypto ETF flows

ETF Flow History: Returns daily spot ETF flow history.

**Included fields:** net flow (USD), token price, per-ticker breakdown.

Sorted by date descending. `symbol`: `BTC`, `ETH`, `XRP`, `SOL`, or `HYPE`.

`GET /gateway/v1/market/etf`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/2b181b24-7b62-4c97-a9d1-d57fd2fa112c

**Docs:** https://docs.asksurf.ai/data-api/market/etf

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | Token symbol. Can be `BTC`, `ETH`, `XRP`, `SOL`, or `HYPE`. |
| `sort_by` | string | No | Field to sort results by |
| `order` | string | No | Sort order |
| `from` | string | No | Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD) |
| `to` | string | No | End of time range. Accepts Unix seconds or date string (YYYY-MM-DD) |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/etf","method":"GET","query":{"symbol":"<string>","sort_by":"<string>","order":"<string>","from":"<string>","to":"<string>"}}'
```

### Exchange flow exchanges

Exchange Flow Exchanges: Returns Hermod's curated exchange filters for exchange-flow metrics: upstream aggregate filters plus 20 high-coverage individual exchanges.

Use the returned `symbol` values as the `exchange` query parameter on `/v1/market/onchain-indicator` when `metric` is one of `exchange-flows/inflow`, `exchange-flows/outflow`, `exchange-flows/netflow`, or `exchange-flows/reserve`.

The curated list intentionally excludes long-tail upstream exchange entities that return empty data or bad-request errors for flow metrics.

`GET /gateway/v1/market/exchange-flow/exchanges`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/a6fa4f82-6b82-448c-bd10-fa99b2a28a4a

**Docs:** https://docs.asksurf.ai/data-api/market/exchange-flow-exchanges

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | Token ticker symbol. Can be `BTC` or `ETH`. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/exchange-flow/exchanges","method":"GET","query":{"symbol":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Fear and greed index

Fear & Greed Index History: Returns Bitcoin Fear & Greed Index history.

**Included fields:** index value (0-100), classification label, BTC price at each data point.

Sorted newest-first. Use `from`/`to` to filter by date range.

`GET /gateway/v1/market/fear-greed`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/d0a896ff-a14f-4b1e-a679-263400c612b5

**Docs:** https://docs.asksurf.ai/data-api/market/fear-greed

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `from` | string | No | Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD) |
| `to` | string | No | End of time range. Accepts Unix seconds or date string (YYYY-MM-DD) |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/fear-greed","method":"GET","query":{"from":"<string>","to":"<string>"}}'
```

### Futures market overview

Futures Market Overview: Returns futures market data across all tracked tokens in a single ranked snapshot.

**Included fields:** open interest, funding rate, long/short ratio, 24h volume.

Sorted by `volume_24h` by default — use `sort_by` to change.

**No pagination** — this endpoint returns the full list in one response. Does NOT accept `limit`, `offset`, or `symbol`; to filter to one token, look it up in the response locally.

`GET /gateway/v1/market/futures`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/1f7cbad1-1628-4de9-82da-6c6e61671bfc

**Docs:** https://docs.asksurf.ai/data-api/market/futures

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sort_by` | string | No | Field to sort results by |
| `order` | string | No | Sort order |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/futures","method":"GET","query":{"sort_by":"<string>","order":"<string>"}}'
```

### Liquidation chart

Liquidation Chart: Returns OHLC-style aggregated liquidation data for a token on a specific exchange.

**Filters:** `symbol`, `exchange`, `interval`.

Useful for charting liquidation volume over time.

`GET /gateway/v1/market/liquidation/chart`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/05561ee8-9780-41fa-ac04-b59538701a45

**Docs:** https://docs.asksurf.ai/data-api/market/liquidation-chart

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | Token ticker symbol like `BTC` or `ETH` |
| `interval` | string | No | Candlestick interval — bucket size for each point in the liquidation chart series: `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `4h`, `6h`, `8h`, `12h`, `1d`, or `1w`. This endpoint uses `interval` only; it does NOT accept `time_range`. Use `from`/`to` to bound the series. |
| `exchange` | string | No | Exchange name. Can be `Binance`, `OKX`, `Bybit`, `Bitget`, `Hyperliquid`, `Gate`, `HTX`, `Bitmex`, `Bitfinex`, `CoinEx`, `Aster`, or `Lighter`. |
| `limit` | integer | No | Results per page |
| `from` | string | No | Start of time range. Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`) |
| `to` | string | No | End of time range. Accepts Unix seconds (`1706745600`) or date string (`2024-02-01`) |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/liquidation/chart","method":"GET","query":{"symbol":"<string>","interval":"<string>","exchange":"<string>","limit":"<integer>","from":"<string>","to":"<string>"}}'
```

### Liquidations by exchange

Liquidation by Exchange: Returns liquidation breakdown by exchange in a single ranked snapshot.

**Included fields:** total, long, and short volumes in USD.

**Filters:** `symbol` and `time_range` (`1h`, `4h`, `12h`, `24h`).

**No pagination and no `interval`** — this endpoint does NOT accept `limit`, `offset`, or `interval`. Returns the full exchange list in one response.

`GET /gateway/v1/market/liquidation/exchange-list`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/d76b005c-0d43-4048-8a43-f01d743bb470

**Docs:** https://docs.asksurf.ai/data-api/market/liquidation-exchange-list

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | No | Token ticker symbol like `BTC` or `ETH` |
| `time_range` | string | No | Window to aggregate over for the snapshot: `1h`, `4h`, `12h`, or `24h`. Returns a single snapshot (not a time-series). This endpoint uses `time_range` only — it does NOT accept `interval`. |
| `sort_by` | string | No | Field to sort results by |
| `order` | string | No | Sort order |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/liquidation/exchange-list","method":"GET","query":{"symbol":"<string>","time_range":"<string>","sort_by":"<string>","order":"<string>"}}'
```

### Large liquidation orders

Large Liquidation Orders: Returns individual large liquidation orders above a USD threshold (`min_amount`, default 10000).

**Filters:** `exchange` and `symbol`.

**Pagination:** `limit`/`offset` page within a bounded, most-recent window. To page beyond that window, shift the time range: set `to` to `oldest_returned_timestamp + 1` (Unix seconds) and repeat, de-duplicating on `order_id`. `to` is **exclusive** (returns rows strictly older than `to`), so the `+1` re-includes the boundary second; using the oldest timestamp itself would skip any rows sharing that second. When `offset` exceeds the window the response returns an empty array with `meta.empty_reason` rather than falsely claiming exhaustion.

For aggregate totals and long/short breakdown by exchange, use `/market/liquidation/exchange-list`. For historical liquidation charts, use `/market/liquidation/chart`.

`GET /gateway/v1/market/liquidation/order`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/daa68b99-c13c-4dba-8d31-87fec0f1d7c0

**Docs:** https://docs.asksurf.ai/data-api/market/liquidation-order

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exchange` | string | No | Exchange name. Can be `Binance`, `OKX`, `Bybit`, `Bitget`, `Hyperliquid`, `Gate`, `HTX`, `Bitmex`, `Bitfinex`, `CoinEx`, `Aster`, or `Lighter`. |
| `symbol` | string | No | Token ticker symbol like `BTC` or `ETH` |
| `min_amount` | string | No | Minimum liquidation amount in USD |
| `side` | string | No | Filter by liquidation side. Omit to return both. |
| `sort_by` | string | No | Field to sort results by |
| `order` | string | No | Sort order |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |
| `from` | string | No | Start of time range (inclusive). Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`) |
| `to` | string | No | End of time range, exclusive (returns rows strictly older than `to`). Accepts Unix seconds (`1706745600`) or date string (`2024-02-01`). To page backward, set this to the oldest returned `timestamp` + 1 and de-duplicate on `order_id`. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/liquidation/order","method":"GET","query":{"exchange":"<string>","symbol":"<string>","min_amount":"<string>","side":"<string>","sort_by":"<string>","order":"<string>","limit":"<integer>","offset":"<integer>","from":"<string>","to":"<string>"}}'
```

### Exchange listing events

Exchange Listing Events: Returns historical exchange listing and delisting events.

**Filters:** date range, exchange, token symbol, product type, event type.

`GET /gateway/v1/market/listing`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/f42c0bf5-6388-4200-9bf4-40243dd54dbd

**Docs:** https://docs.asksurf.ai/data-api/market/listing

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `from` | string | Yes | Start date (YYYY-MM-DD or ISO 8601) |
| `to` | string | No | End date (defaults to now) |
| `symbol` | string | No | Filter by token symbol |
| `exchange` | string | No | Filter by exchange name |
| `product` | string | No | Filter by product type |
| `type` | string | No | Event type filter |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/listing","method":"GET","query":{"from":"<string>","to":"<string>","symbol":"<string>","exchange":"<string>","product":"<string>","type":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### On-chain indicator

On-Chain Indicator: Returns on-chain indicator time-series for BTC or ETH.

**Available metrics:** `nupl`, `sopr`, `mvrv`, `puell-multiple`, `nvm`, `nvt`, `nvt-golden-cross`, `exchange-flows` (inflow/outflow/netflow/reserve).

**Long ranges:** each response is capped at about 100 data points. When `meta.has_more=true`, split `from`/`to` into smaller windows (about 90 days for daily data) and merge by timestamp client-side. For exchange-flow metrics, `all_exchange`, `spot_exchange`, and `derivative_exchange` are aggregate filters, not sums over the curated individual exchange list.

`GET /gateway/v1/market/onchain-indicator`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/48b790bb-ab1e-4409-8e56-a56dba6814cc

**Docs:** https://docs.asksurf.ai/data-api/market/onchain-indicator

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | Token ticker symbol. Can be `BTC` or `ETH`. |
| `metric` | string | Yes | On-chain metric name. Can be `nupl`, `sopr`, `mvrv`, `puell-multiple`, `nvm`, `nvt`, `nvt-golden-cross`, or `exchange-flows/{inflow,outflow,netflow,reserve}`. |
| `granularity` | string | No | Aggregation granularity. |
| `from` | string | No | Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD). Defaults to 90 days ago when omitted. Maximum range is 365 days. Responses are capped at about 100 data points; when meta.has_more is true, split from/to into smaller windows (about 90 days for daily data). |
| `to` | string | No | End of time range. Accepts Unix seconds or date string (YYYY-MM-DD). Defaults to today when omitted. Maximum range is 365 days. Responses are capped at about 100 data points; when meta.has_more is true, split from/to into smaller windows (about 90 days for daily data). |
| `exchange` | string | No | Curated exchange filter for exchange-flow metrics. Use /v1/market/exchange-flow/exchanges to list labels. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/onchain-indicator","method":"GET","query":{"symbol":"<string>","metric":"<string>","granularity":"<string>","from":"<string>","to":"<string>","exchange":"<string>"}}'
```

### Options market data

Options Market Data: Returns options market data for a `symbol`.

**Included fields:** open interest, volume, put/call ratio, max pain price.

`GET /gateway/v1/market/options`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/3439c19c-d039-4ae6-955e-468429e9952d

**Docs:** https://docs.asksurf.ai/data-api/market/options

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | Token symbol. Can be `BTC`, `ETH`, `SOL`, `XRP`, `BNB`, `DOGE`, `ADA`, or `AVAX`. |
| `sort_by` | string | No | Field to sort results by |
| `order` | string | No | Sort order |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/options","method":"GET","query":{"symbol":"<string>","sort_by":"<string>","order":"<string>"}}'
```

### Token price history

Token Price History: Returns historical price data points for a token over a specified time range.

**Time range options:**
- Predefined: `1d`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `max`
- Custom: use `from` / `to` (Unix seconds or `YYYY-MM-DD`)

**Granularity** is automatic based on range:
- `1d` → 5-minute intervals
- `7d`–`90d` → hourly
- `180d`+ → daily

`GET /gateway/v1/market/price`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/7d04c87e-9a0e-4315-ab10-4c2a0ee8558c

**Docs:** https://docs.asksurf.ai/data-api/market/price

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | Single token ticker symbol like `BTC`, `ETH`, or `SOL` (multi-symbol not supported) |
| `time_range` | string | No | Window of historical data to return: `1d`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, or `max`. Ignored when `from`/`to` are set. This endpoint uses `time_range` only — it does NOT accept `interval`; bucket granularity is chosen server-side based on the window size. |
| `from` | string | No | Start of custom date range (Unix timestamp or YYYY-MM-DD). Must be used together with `to`. Overrides `time_range` when set. |
| `to` | string | No | End of custom date range (Unix timestamp or YYYY-MM-DD). Must be used together with `from`. Overrides `time_range` when set. |
| `currency` | string | No | Quote currency like `usd`, `eur`, or `btc` |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/price","method":"GET","query":{"symbol":"<string>","time_range":"<string>","from":"<string>","to":"<string>","currency":"<string>"}}'
```

### Technical indicator

Technical Indicator: Returns a technical indicator for a trading pair on a given exchange and interval.

**Modes:**
- Set `from`/`to` for time-series
- Omit for latest value only

**Indicator-specific tuning** via `options` (e.g. `period:7`, `fast_period:8,slow_period:21,signal_period:5`, `period:10,stddev:1.5`).

**Available indicators:** `rsi`, `macd`, `ema`, `sma`, `bbands`, `stoch`, `adx`, `atr`, `cci`, `obv`, `vwap`, `dmi`, `ichimoku`, `supertrend`.

`GET /gateway/v1/market/price-indicator`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/979c081a-827b-4bfd-a197-27378cba6a9c

**Docs:** https://docs.asksurf.ai/data-api/market/price-indicator

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `indicator` | string | Yes | Technical indicator name. Can be `rsi`, `macd`, `ema`, `sma`, `bbands`, `stoch`, `adx`, `atr`, `cci`, `obv`, `vwap`, `dmi`, `ichimoku`, or `supertrend`. |
| `symbol` | string | Yes | Trading pair as `BTC/USDT` or bare symbol like `BTC` |
| `interval` | string | No | Candlestick interval — bucket size for each point in the indicator series: `1m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `12h`, `1d`, or `1w`. This endpoint uses `interval` only; it does NOT accept `time_range`. Use `from`/`to` to bound the series. |
| `exchange` | string | No | Exchange for price data. Can be `binance`, `bybit`, `coinbase`, or `kraken`. |
| `from` | string | No | Start of time range. When set, returns time-series instead of latest value. Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`) |
| `to` | string | No | End of time range. Defaults to now when from is set. Accepts Unix seconds (`1706745600`) or date string (`2024-02-01`) |
| `options` | string | No | Indicator-specific options as comma-separated key:value pairs. Available options by indicator: `period` — lookback period for rsi (default 14), sma (default 20), ema (default 20), bbands (default 20), adx (default 14), atr (default 14), cci (default 20), dmi (default 14), stoch (default 14), supertrend (default 10). `stddev` — standard deviation for bbands (default 2). `multiplier` — multiplier for supertrend (default 3). `fast_period` — MACD fast EMA (default 12). `slow_period` — MACD slow EMA |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/price-indicator","method":"GET","query":{"indicator":"<string>","symbol":"<string>","interval":"<string>","exchange":"<string>","from":"<string>","to":"<string>","options":"<string>"}}'
```

### Token public sales

Public Sale / Crowdsale: Returns public sale (IDO/ICO/IEO) information for a project.

Includes sale type, status, price, raise amount, and ROI data.

`GET /gateway/v1/market/public-sale`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/aaa2ed97-5ff8-4ba1-abf7-35402887813a

**Docs:** https://docs.asksurf.ai/data-api/market/public-sale

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Surf project UUID |
| `q` | string | No | Project name or symbol for entity resolution |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/public-sale","method":"GET","query":{"id":"<string>","q":"<string>"}}'
```

### Token rankings

Token Rankings: Returns a token leaderboard sorted by market cap, 24h change, or volume. Each entry includes price, market cap, FDV, supply, ATH/ATL, and 24h range. Supports category filtering (MEME, AI, L1, L2, DEFI, GAMING, etc.).

**Available metrics:** `market_cap`, `top_gainers`, `top_losers`, `volume`.

**Note:** `top_gainers` and `top_losers` rank by 24h price change within the top 250 coins by market cap.

For circulating supply, FDV, ATH/ATL, use `/project/detail?fields=token_info`.

`GET /gateway/v1/market/ranking`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/4b256942-93e9-450b-b66f-bbdd099dbeb3

**Docs:** https://docs.asksurf.ai/data-api/market/ranking

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sort_by` | string | No | Field to sort by. `market_cap` sorts by total market capitalisation, `change_24h` sorts by 24-hour price change percentage (fetches top 250 by market cap then sorts client-side), `volume_24h` sorts by 24-hour trading volume. |
| `order` | string | No | Sort order: `desc` (default, highest first) or `asc` (lowest first). |
| `category` | string | No | Optional token category filter. When provided, results are limited to coins in that category. Supported values: MEME, AI, AI_AGENTS, L1, L2, DEFI, GAMING, STABLECOIN, RWA, DEPIN, SOL_ECO, BASE_ECO, LST. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/ranking","method":"GET","query":{"sort_by":"<string>","order":"<string>","category":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Token generation events

Token Generation Event: Returns Token Generation Event (TGE) status for a project.

Includes current status, last event time, and listing exchanges.

`GET /gateway/v1/market/tge`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/860111f2-17dd-42b0-8927-e27fc643f04d

**Docs:** https://docs.asksurf.ai/data-api/market/tge

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Surf project UUID |
| `q` | string | No | Project name or symbol for entity resolution |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/market/tge","method":"GET","query":{"id":"<string>","q":"<string>"}}'
```

### News article detail

News Article Detail: Returns the full content of a single news article by its ID (returned as `id` in feed and search results).

`GET /gateway/v1/news/detail`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/8e9a3b0b-f8b0-4896-abd6-29681f5dbcac

**Docs:** https://docs.asksurf.ai/data-api/news/detail

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Article ID (returned as id in feed/search results) |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/news/detail","method":"GET","query":{"id":"<string>"}}'
```

### Crypto news feed

Crypto News Feed: Returns crypto news from major sources.

**Filters:** `source` (enum), `project`, and time range (`from`/`to`).

**Sort:** `recency` (default) or `trending`.

Use the detail endpoint with article `id` for full content.

`GET /gateway/v1/news/feed`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/40378cb7-d370-499f-82bb-972aaed0be10

**Docs:** https://docs.asksurf.ai/data-api/news/feed

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `source` | string | No | Filter by news source |
| `project` | string | No | Comma-separated project names to filter by |
| `from` | string | No | Filter articles published on or after this time. Accepts Unix seconds or date string (2024-01-01) |
| `to` | string | No | Filter articles published on or before this time. Accepts Unix seconds or date string (2024-02-01) |
| `sort_by` | string | No | Sort order: recency (newest first) or trending (deterministic newest-first alias until engagement ranking is available) |
| `limit` | integer | No | Results per page (max 50) |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/news/feed","method":"GET","query":{"source":"<string>","project":"<string>","from":"<string>","to":"<string>","sort_by":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Bridge protocol ranking

Bridge Protocol Ranking: List bridge protocols ranked by USD volume over a time range. Example: use this when you need bridge leaderboard data instead of raw SQL.

`GET /gateway/v1/onchain/bridge/ranking`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/42389629-9e56-4728-8e5a-d8a18f41d44e

**Docs:** https://docs.asksurf.ai/data-api/onchain/bridge-ranking

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `time_range` | string | No | Window to aggregate bridge volume over: `7d`, `30d`, `90d`, `180d`, `1y`, or `all`. Returns a single ranked snapshot (not a time-series). This endpoint uses `time_range` only — it does NOT accept `interval`. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/bridge/ranking","method":"GET","query":{"time_range":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### DEX protocol activity

DEX Protocol Activity: Active traders, trade count, and USD volume for a DEX **protocol** (or a specific router contract), as a single aggregate or a daily series (`group_by=day`).

**Lookup:** `chain` + exactly one of `project` (e.g. `uniswap`, `pancakeswap`) or `address` (a router measured as `tx_to`).

**Related:** per-swap rows for a single token → `/v1/token/dex-trades`.

**Chains:** Ethereum, Base, BSC, Arbitrum, Tron · **Refresh:** ~24h · USD volume lags ~3 days (see `enriched_ratio`).

`GET /gateway/v1/onchain/dex/activity`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/d4d2a10f-97c5-44b4-b6b9-9841dd4279f9

**Docs:** https://docs.asksurf.ai/data-api/onchain/dex-activity

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chain` | string | Yes | Chain to query. |
| `project` | string | No | DEX project name (e.g. `uniswap`, `pancakeswap`, `aerodrome`). Exactly one of `project` / `address` is required. |
| `address` | string | No | A specific router/contract measured as `tx_to`. Exactly one of `project` / `address` is required. |
| `time_range` | string | No | Look-back window (hard 90d cap). Overridden by `from`/`to` when set. |
| `from` | string | No | Start of range — Unix seconds or YYYY-MM-DD. With `to`, the range may span at most 90 days. |
| `to` | string | No | End of range — Unix seconds or YYYY-MM-DD. Without `from`, the window is `time_range` ending at `to`. |
| `group_by` | string | No | `total` = single aggregate; `day` = daily series (newest first). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/dex/activity","method":"GET","query":{"chain":"<string>","project":"<string>","address":"<string>","time_range":"<string>","from":"<string>","to":"<string>","group_by":"<string>"}}'
```

### Current gas price

Current Gas Price: Look up the current gas price for one EVM chain. Example: `chain=ethereum`.

This endpoint uses `eth_gasPrice` JSON-RPC and returns gas price in both wei and Gwei.

Supported chains: `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `base`, `avalanche`, `fantom`, `linea`, `cyber`.

`GET /gateway/v1/onchain/gas-price`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/1c485f11-cd44-4c5c-9d34-72ba401bb8c3

**Docs:** https://docs.asksurf.ai/data-api/onchain/gas-price

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chain` | string | Yes | Chain. Can be `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `base`, `avalanche`, `fantom`, `linea`, or `cyber`. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/gas-price","method":"GET","query":{"chain":"<string>"}}'
```

### Blockchain structured query

Blockchain Structured Query: Send a JSON object describing the query. Example: `{"source":"agent.ethereum_dex_trades","fields":["block_time"],"filters":[{"field":"block_date","op":"gte","value":"2025-03-01"}],"limit":1}`.

Use this endpoint when you want structured filtering without writing raw SQL. Discover tables and columns first with `GET /v1/onchain/schema`.

Key rules:
- Source format: `agent.<table_name>`
- Max 10,000 rows (default 20), 30s timeout
- Always filter on `block_date` for large tables
- **Never filter by** `symbol` — it is unindexed (full scan). To resolve a ticker to a contract address, use `GET /v1/search/token?q={symbol}&chain={chain}` and filter by `contract_address` instead
- For transfer tables, `amount` is decimal-adjusted display units; `amount_raw` is the original base-unit value

Data refresh: ~24 hours.

Example

```json
{
  "source": "agent.ethereum_dex_trades",
  "fields": ["block_time", "project", "token_pair", "amount_usd", "taker"],
  "filters": [

`POST /gateway/v1/onchain/query`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/fb5a6b67-bbba-4398-b70c-7b51e9cd6a5e

**Docs:** https://docs.asksurf.ai/data-api/onchain/query

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `$schema` | string | No | A URL to the JSON Schema for this object. |
| `fields` | string | No | Columns to return. Omit to return all columns. |
| `filters` | object | No | WHERE conditions (ANDed together) |
| `limit` | integer | No | Max rows to return. Default 20, max 10000 |
| `offset` | integer | No | Rows to skip for pagination. Default 0 |
| `sort` | object | No | ORDER BY clauses |
| `source` | string | Yes | Fully-qualified table name like `agent.ethereum_yields_daily`. Use GET /v1/onchain/schema for available tables. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/query","body":{"$schema":"<string>","fields":"<string>","filters":"<object>","limit":"<integer>","offset":"<integer>","sort":"<object>","source":"<string>"}}'
```

### On-chain table schema

On-Chain Table Schema: Discover tables and columns before writing SQL or structured queries. Example: call this endpoint first, then use `agent.ethereum_dex_trades` in `/v1/onchain/query` or `/v1/onchain/sql`.

The response includes database name, table name, column names, types, and comments. Pass the optional `table` parameter to include bounded physical source metadata: engine, partition key, sorting key, primary key, row estimate, and compressed bytes.

For transfer tables, `amount` is decimal-adjusted display units and `amount_raw` is the original base-unit value.

`GET /gateway/v1/onchain/schema`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/a0b45926-26e3-4ab6-9f15-801a3877b598

**Docs:** https://docs.asksurf.ai/data-api/onchain/schema

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `table` | string | No | Optional logical table name from the agent database. Use this to include bounded physical partition, ordering-key, and size metadata. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/schema","method":"GET","query":{"table":"<string>"}}'
```

### Blockchain SQL query

Blockchain SQL Query: Run a raw ClickHouse `SELECT` query against blockchain data.

All tables live in the **agent** database. Discover tables and columns first with `GET /v1/onchain/schema`.

Send a JSON object, not raw SQL text. Example: `{"sql":"SELECT ...","max_rows":1000}`.

Execution modes
- The default response is synchronous and has a 30s timeout.
- For queries that may exceed that window, send `Prefer: respond-async`. The same request is accepted as a durable job with `202 Accepted` and `Preference-Applied: respond-async`.
- Send a stable `Idempotency-Key` with `respond-async` so equivalent client retries reuse the retained job.
- A synchronous timeout is non-retryable and returns `recommended_action: use_async_job` plus the async job URL. Do not resubmit the synchronous request automatically.
- Synchronous and asynchronous ClickHouse executions share one cluster-wide per-owner concurrency budget. Accepted async jobs remain queued while that owner's execution slots are occupie

`POST /gateway/v1/onchain/sql`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/05c7735a-4bbe-48fd-96b0-4c1560c4c3e6

**Docs:** https://docs.asksurf.ai/data-api/onchain/sql

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `$schema` | string | No | A URL to the JSON Schema for this object. |
| `max_rows` | integer | No | Maximum number of rows to return |
| `sql` | string | Yes | Send a JSON object with the sql field. Example: {"sql":"SELECT 1"}. Use GET /v1/onchain/schema for tables and columns. Transfer table amount is decimal-adjusted; amount_raw is the original base-unit value. Use single quotes for ClickHouse strings. Example: toDate('2026-04-07'). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/sql","body":{"$schema":"<string>","max_rows":"<integer>","sql":"<string>"}}'
```

### Async SQL job submit

Submit Asynchronous Blockchain SQL Job: Accepts a read-only SQL query for durable background execution. Returns a stable job and ClickHouse query ID immediately. Reusing the same Idempotency-Key, or submitting SQL equivalent after whitespace and operator-spacing normalization with the same max_rows while its retained job exists, returns the existing job without starting another execution. Accepted jobs remain queued while the owner's cluster-wide ClickHouse execution budget is occupied by synchronous or asynchronous work.

`POST /gateway/v1/onchain/sql/jobs`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/6cbdff0d-3df7-48cd-abfc-04966546dea3

**Docs:** https://docs.asksurf.ai/data-api/onchain/sql

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `$schema` | string | No | A URL to the JSON Schema for this object. |
| `max_rows` | integer | No | Maximum number of result rows to retain |
| `sql` | string | Yes | Exact read-only ClickHouse SQL to execute asynchronously. The submitted SQL and date range are preserved. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/sql/jobs","body":{"$schema":"<string>","max_rows":"<integer>","sql":"<string>"}}'
```

### Async SQL job status

Get Asynchronous Blockchain SQL Job: Returns durable job status, elapsed time, ClickHouse progress counters, retry semantics, and result links. Polling never starts another ClickHouse execution.

`GET /gateway/v1/onchain/sql/jobs/{job_id}`

**Cost:** Free. Calls cost nothing.

**Page:** https://www.orthogonal.com/api/surf/aeb503b2-b709-4f07-ba23-8da398e73df2

**Docs:** https://docs.asksurf.ai/data-api/onchain/sql

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `job_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {job_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/sql/jobs/{job_id}","method":"GET"}'
```

### Async SQL job cancel

Cancel Asynchronous Blockchain SQL Job: Durably requests cancellation and returns the current job state. Queued jobs become canceled immediately. Task workers asynchronously stop and verify running ClickHouse queries; poll the job until it reaches canceled or failed.

`DELETE /gateway/v1/onchain/sql/jobs/{job_id}`

**Cost:** Free. Calls cost nothing.

**Page:** https://www.orthogonal.com/api/surf/a6e00f7d-3c58-494e-b924-7345ae83382d

**Docs:** https://docs.asksurf.ai/data-api/onchain/sql

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `job_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {job_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/sql/jobs/{job_id}","method":"DELETE"}'
```

### Async SQL job results

Download Asynchronous Blockchain SQL Results: Returns the retained complete result as the standard JSON data envelope or as a CSV attachment. Results are available for 24 hours and are isolated to the authenticated tenant or user.

`GET /gateway/v1/onchain/sql/jobs/{job_id}/results`

**Cost:** Free. Calls cost nothing.

**Page:** https://www.orthogonal.com/api/surf/daf2fb75-970f-428f-964a-e0163da92850

**Docs:** https://docs.asksurf.ai/data-api/onchain/sql

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `job_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `format` | string | No | Result representation |

```bash
# Replace {job_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/sql/jobs/{job_id}/results","method":"GET","query":{"format":"<string>"}}'
```

### SQL query preflight

Preflight Blockchain SQL Query: Validate and estimate a read-only ClickHouse query before executing it.

This endpoint runs `EXPLAIN ESTIMATE` and does not execute the submitted query. It returns:
- Logical schema plus bounded physical source metadata
- Partition, sorting, and primary-key expressions
- Estimated parts, rows, marks, and bytes
- The final server-bounded SQL and scan budgets
- Machine-readable guardrail warnings with recommended actions

Use `GET /v1/onchain/schema?table=<name>` for metadata-only discovery. Preflight accepts the same JSON shape and SQL safety rules as `POST /v1/onchain/sql`, but missing pruning filters are returned as structured rejection warnings rather than running the query.

The planner rejects address columns wrapped in `lower()` and transfer-table predicates that combine `from` and `to` with OR. Normalize address literals before submission, compare stored lowercase columns directly, and split incoming/outgoing transfer predicates into projection-fri

`POST /gateway/v1/onchain/sql/preflight`

**Cost:** Up to $0.03924 per call. Response-based: the price is worked out from the usage reported in the response, never more than $0.03924 per call. You aren't charged for failed calls. A wallet payment for a failed call is refunded.
- If you pay with a wallet (x402, MPP or Nanopayments), you pay this request's price before the call, not the final price from the response

Use `"dryRun": true` in the Run API request to see a request's price before calling.

**Page:** https://www.orthogonal.com/api/surf/b282a718-0cf7-4a94-a35a-c255b4489d91

**Docs:** https://docs.asksurf.ai/data-api/onchain/sql

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `$schema` | string | No | A URL to the JSON Schema for this object. |
| `max_rows` | integer | No | Maximum result rows in the final server-bounded execution plan |
| `sql` | string | Yes | Read-only ClickHouse SELECT/WITH query to validate and estimate without executing it |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/sql/preflight","body":{"$schema":"<string>","max_rows":"<integer>","sql":"<string>"}}'
```

### Transaction details

Transaction Details by Hash: Look up one transaction by hash. Example: `chain=ethereum` with a 0x-prefixed 64-character hash.

All numeric fields are hex-encoded. Convert them with `parseInt(hex, 16)`.

Supported chains: `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `base`, `avalanche`, `fantom`, `linea`, `cyber`.

`GET /gateway/v1/onchain/tx`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/7f97ef7e-259d-4830-9ce6-8c9451bd94cb

**Docs:** https://docs.asksurf.ai/data-api/onchain/tx

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `hash` | string | Yes | Transaction hash (0x-prefixed hex) |
| `chain` | string | Yes | Chain. Can be `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `base`, `avalanche`, `fantom`, `linea`, or `cyber`. |
| `include` | string | No | Comma-separated enrichments to attach. Currently valid: `labels` — adds `from_label` and `to_label` fields with entity information for the from/to addresses. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/tx","method":"GET","query":{"hash":"<string>","chain":"<string>","include":"<string>"}}'
```

### Yield pool ranking

Yield Pool Ranking: List individual DeFi yield pools ranked by APY or TVL. Example: filter by protocol like `lido` or `aave` for pool-level yield data.

`GET /gateway/v1/onchain/yield/ranking`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/a1487885-4e6d-4f26-ace7-aa40d080f350

**Docs:** https://docs.asksurf.ai/data-api/onchain/yield-ranking

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `project` | string | No | Filter by protocol name like `lido`, `aave`, or `uniswap` |
| `sort_by` | string | No | Ranking metric: `apy` or `tvl_usd`. When sorted by `apy`, only pools with TVL >= $100k are included |
| `order` | string | No | Sort direction |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/onchain/yield/ranking","method":"GET","query":{"project":"<string>","sort_by":"<string>","order":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Prediction market analytics

Prediction Market Analytics: Trends, top markets, momentum distribution, and per-market momentum signals for prediction markets.

**Platform-wide totals:** Omit `category` to get aggregated volume/OI/market-count across the entire prediction market (Polymarket + Kalshi combined). Use `platform` to filter to one exchange. This is the recommended way to answer questions like "What is Polymarket's total volume this week?" or "How does Kalshi volume compare to Polymarket?"

**Category drill-down:** Provide `category` to scope all data to one category (e.g. crypto, politics).

Combines volume/OI time series, top markets by open interest, momentum summary (price/volume signal distribution), and per-market momentum signals (price changes, volume direction, whale flows).

**Note on top_markets:** When both `category` and `platform` are omitted, top markets are ranked globally by open interest. Because Polymarket OI is significantly larger than Kalshi OI, the list will skew heavily toward Polym

`GET /gateway/v1/prediction-market/analytics`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/45cfadad-38be-43ba-add3-d27f76e8e330

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/analytics

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category to analyze. Omit to get platform-wide totals across all categories. |
| `platform` | string | No | Filter to one platform |
| `time_range` | string | No | Window for category trends: `7d`, `30d`, `90d`, `180d`, or `1y`. Bucket size is fixed at 1 day — this endpoint uses `time_range` only and does NOT accept `interval`. |
| `top_n` | integer | No | Number of top markets to include |
| `sort_by` | string | No | Sort field for momentum markets |
| `order` | string | No | Sort direction |
| `limit` | integer | No | Limit for momentum markets list |
| `offset` | integer | No | Pagination offset for momentum markets |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/analytics","method":"GET","query":{"category":"<string>","platform":"<string>","time_range":"<string>","top_n":"<integer>","sort_by":"<string>","order":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Prediction market correlations

Market Correlations: Returns 30-day Pearson price correlation pairs between Polymarket markets within a category.

Correlation data covers the top 100 markets by 7-day volume globally; lower-volume markets may not have correlation data.

Filter by `condition_id` to find all markets correlated with a specific market, or set `min_correlation` to control the threshold.

The `category` parameter is required.

**Data refresh:** ~5 minutes.

`GET /gateway/v1/prediction-market/correlations`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/c0740bb7-90b0-4374-b0d6-dd30f8a36116

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/correlations

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Category (correlations are within-category only) |
| `condition_id` | string | No | Filter to pairs involving this market |
| `min_correlation` | number | No | Minimum absolute correlation |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/correlations","method":"GET","query":{"category":"<string>","condition_id":"<string>","min_correlation":"<number>","limit":"<integer>","offset":"<integer>"}}'
```

### Kalshi events

Kalshi Events: Returns Kalshi events with nested markets, optionally filtered by `event_ticker`.

Each event includes market count and a list of markets.

**Data refresh:** ~30 minutes

`GET /gateway/v1/prediction-market/kalshi/events`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/3fd78642-303c-4a43-b941-52bf3a7c91f6

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/kalshi-events

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event_ticker` | string | No | Event ticker identifier. When omitted, returns top active events by volume. Use GET /v1/search/prediction-market?platform=kalshi&q={keyword} to discover valid tickers. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/kalshi/events","method":"GET","query":{"event_ticker":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Kalshi markets

Kalshi Markets: Returns Kalshi markets, optionally filtered by `market_ticker`.

Each market includes price, volume, and status.

**Data refresh:** ~30 minutes

`GET /gateway/v1/prediction-market/kalshi/markets`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/c56c4f8d-847e-4e7f-b79f-cf86013d4d4a

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/kalshi-markets

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `market_ticker` | string | No | Market ticker identifier. When omitted, returns top active markets by volume. Use GET /v1/search/prediction-market?platform=kalshi&q={keyword} to discover valid tickers. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/kalshi/markets","method":"GET","query":{"market_ticker":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Kalshi open interest

Kalshi Open Interest History: Daily open interest time series for a Kalshi market.

**Data refresh:** ~30 minutes

`GET /gateway/v1/prediction-market/kalshi/open-interest`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/b089c5bb-0091-48c9-92d7-e85e7857105e

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/kalshi-open-interest

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ticker` | string | Yes | Market ticker identifier. Use GET /v1/prediction-market/kalshi/markets or GET /v1/search/prediction-market?platform=kalshi&q={keyword} to discover valid tickers. |
| `time_range` | string | No | Window of history to return: `7d`, `30d`, `90d`, `180d`, or `1y`. This endpoint uses `time_range` only — it does NOT accept `interval`. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/kalshi/open-interest","method":"GET","query":{"ticker":"<string>","time_range":"<string>"}}'
```

### Kalshi orderbook history

Kalshi Orderbook History: Historical orderbook snapshots for a Kalshi market. Returns yes-side bid/ask levels. Timestamps in milliseconds, prices in cents.

Data refresh: ~5 minutes

`GET /gateway/v1/prediction-market/kalshi/orderbooks`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/e253ec2d-b973-4c1a-9fac-25f7f780aa92

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/kalshi-orderbooks

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ticker` | string | Yes | Kalshi market ticker |
| `start_time` | integer | No | Start time in Unix milliseconds. 0 means 7 days ago. |
| `end_time` | integer | No | End time in Unix milliseconds. 0 means current time. |
| `limit` | integer | No | Maximum number of snapshots to return |
| `pagination_key` | string | No | Base64 cursor for pagination |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/kalshi/orderbooks","method":"GET","query":{"ticker":"<string>","start_time":"<integer>","end_time":"<integer>","limit":"<integer>","pagination_key":"<string>"}}'
```

### Kalshi price history

Kalshi Price History: Price time series for a Kalshi market with daily or hourly OHLC data, or latest price from recent trades.

**Data refresh:** ~30 minutes

`GET /gateway/v1/prediction-market/kalshi/prices`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/4d56f52b-3835-40bc-9dc2-1268390be31c

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/kalshi-prices

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ticker` | string | Yes | Market ticker identifier. Use GET /v1/prediction-market/kalshi/markets or GET /v1/search/prediction-market?platform=kalshi&q={keyword} to discover valid tickers. |
| `time_range` | string | No | Window of history to return: `7d`, `30d`, `90d`, `180d`, or `1y`. Ignored when `interval=latest`. Distinct from `interval` (which sets bucket size within the window). |
| `interval` | string | No | Bucket size for each point in the series: `1h` (hourly OHLC), `1d` (daily OHLC), or `latest` (single most-recent trade price). Distinct from `time_range` (window size). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/kalshi/prices","method":"GET","query":{"ticker":"<string>","time_range":"<string>","interval":"<string>"}}'
```

### Kalshi trades

Kalshi Trades: Returns individual trade records for a Kalshi market.

**Filters:** `taker_side`, `min_contracts`, and date range.

**Sort:** `timestamp` or `num_contracts`.

**Data refresh:** real-time

`GET /gateway/v1/prediction-market/kalshi/trades`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/ae95be61-95fa-4cf0-a1e9-b6d4978c5531

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/kalshi-trades

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ticker` | string | Yes | Market ticker identifier. Use GET /v1/prediction-market/kalshi/markets or GET /v1/search/prediction-market?platform=kalshi&q={keyword} to discover valid tickers. |
| `taker_side` | string | No | Filter by taker side: `yes` or `no` |
| `min_amount` | integer | No | Minimum notional volume in USD (each contract = $1) |
| `from` | string | No | Start of time range. Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`) |
| `to` | string | No | End of time range. Accepts Unix seconds (`1706745600`) or date string (`2024-02-01`) |
| `sort_by` | string | No | Field to sort results by |
| `order` | string | No | Sort order |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/kalshi/trades","method":"GET","query":{"ticker":"<string>","taker_side":"<string>","min_amount":"<integer>","from":"<string>","to":"<string>","sort_by":"<string>","order":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Kalshi volume history

Kalshi Volume History: Daily trading volume time series for a Kalshi market.

**Data refresh:** ~30 minutes

`GET /gateway/v1/prediction-market/kalshi/volumes`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/f274ec7f-a73f-47db-8447-b5c5865c4f0c

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/kalshi-volumes

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ticker` | string | Yes | Market ticker identifier. Use GET /v1/prediction-market/kalshi/markets or GET /v1/search/prediction-market?platform=kalshi&q={keyword} to discover valid tickers. |
| `time_range` | string | No | Window of history to return: `7d`, `30d`, `90d`, `180d`, or `1y`. This endpoint uses `time_range` only — it does NOT accept `interval`. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/kalshi/volumes","method":"GET","query":{"ticker":"<string>","time_range":"<string>"}}'
```

### Matched market daily comparison

Cross-Platform Daily Comparison (Polymarket <> Kalshi): Returns daily volume and open interest comparison for a specific Polymarket <> Kalshi matched pair.

Both `polymarket_condition_id` and `kalshi_market_ticker` are required. Use `matching-market-pairs` to discover matched pairs first.

**Volume units:** Polymarket = USD, Kalshi = contracts.

`GET /gateway/v1/prediction-market/matching/daily`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/e12dd741-1aa0-40c7-920b-afef510be2e2

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/matching-daily

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `polymarket_condition_id` | string | Yes | Polymarket condition ID |
| `kalshi_market_ticker` | string | Yes | Kalshi market ticker |
| `time_range` | string | No | Window of daily data to return: `1d`, `7d`, `30d`, `90d`, `180d`, `1y`, or `all`. Bucket size is fixed at 1 day — this endpoint uses `time_range` only and does NOT accept `interval`. |
| `limit` | integer | No | Maximum rows |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/matching/daily","method":"GET","query":{"polymarket_condition_id":"<string>","kalshi_market_ticker":"<string>","time_range":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Matched market pairs

Cross-Platform Prediction Market Matcher (Polymarket <> Kalshi): Cross-platform prediction market pair matcher — finds the same event listed on both Polymarket and Kalshi, with live price spread data. This is prediction-market only (Polymarket and Kalshi). For crypto exchange markets, use `exchange-markets`.

Filter by category, match type, confidence score, or look up a specific market's cross-platform counterpart via `polymarket_condition_id` or `kalshi_market_ticker`.

Each pair includes current prices and spread percentage for arbitrage analysis. Sort by `spread_pct` to find the widest spreads.

**Data refresh:** ~5 minutes

`GET /gateway/v1/prediction-market/matching/pairs`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/104c6b45-df77-426a-b521-1ec877447d08

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/matching-pairs

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Filter by category |
| `match_type` | string | No | Filter by match type |
| `active_only` | boolean | No | Only return pairs where both markets are currently active |
| `min_confidence` | integer | No | Minimum confidence score (0-100) |
| `polymarket_condition_id` | string | No | Find match for this Polymarket market |
| `kalshi_market_ticker` | string | No | Find match for this Kalshi market |
| `sort_by` | string | No | Sort field |
| `order` | string | No | Sort order |
| `limit` | integer | No | Maximum rows to return |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/matching/pairs","method":"GET","query":{"category":"<string>","match_type":"<string>","active_only":"<boolean>","min_confidence":"<integer>","polymarket_condition_id":"<string>","kalshi_market_ticker":"<string>","sort_by":"<string>","order":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Polymarket events

Polymarket Events: Returns Polymarket events with nested markets, optionally filtered by `event_slug`.

Each event includes aggregated status, volume, and a list of markets with `side_a`/`side_b` outcomes.

**Data refresh:** ~30 minutes

`GET /gateway/v1/prediction-market/polymarket/events`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/c3353bdc-0b58-419b-9e4d-1e8b20e78350

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/polymarket-events

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event_slug` | string | Yes | Polymarket event slug (identifies a multi-outcome question with several nested markets). Known World Cup match sibling slugs are expanded to the canonical match group. Discover slugs via /v1/search/prediction-market?platform=polymarket&q={keyword}. For a single Yes/No market, use /polymarket/markets with market_slug instead — this endpoint only accepts event_slug, not market_slug. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/polymarket/events","method":"GET","query":{"event_slug":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Polymarket leaderboard

Polymarket Leaderboard: Returns a ranked leaderboard of Polymarket traders by realized PnL, volume, or trade count.

Sortable by `pnl`, `volume`, or `trade_count`. Each entry includes the wallet address and aggregate trading statistics.

**Data refresh:** ~5 minutes.

`GET /gateway/v1/prediction-market/polymarket/leaderboard`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/c016a237-de67-4d1b-b986-7b716bfda00b

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/polymarket-leaderboard

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sort_by` | string | No | Ranking metric |
| `order` | string | No | Sort direction |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/polymarket/leaderboard","method":"GET","query":{"sort_by":"<string>","order":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Polymarket markets

Polymarket Markets: Returns Polymarket markets, optionally filtered by `market_slug`.

Each market includes `side_a` and `side_b` outcomes. Current prices are available via `/polymarket/prices` using the `condition_id`.

**Data refresh:** ~30 minutes

`GET /gateway/v1/prediction-market/polymarket/markets`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/7f9d82f3-02b5-45bd-ab65-cf9048155df2

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/polymarket-markets

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `market_slug` | string | Yes | Polymarket market slug (identifies a single Yes/No outcome). Discover slugs via /v1/search/prediction-market?platform=polymarket&q={keyword}. For a multi-outcome question (e.g. 'who wins the 2024 election'), use the /polymarket/events endpoint with event_slug instead. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/polymarket/markets","method":"GET","query":{"market_slug":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Polymarket open interest

Polymarket Open Interest History: Daily open interest time series showing total value locked in a Polymarket market.

**Data refresh:** ~30 minutes

`GET /gateway/v1/prediction-market/polymarket/open-interest`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/3437fe9a-a40a-4406-989e-84b7b86b18e5

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/polymarket-open-interest

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `condition_id` | string | Yes | Market condition identifier |
| `time_range` | string | No | Window of history to return: `7d`, `30d`, `90d`, `180d`, or `1y`. This endpoint uses `time_range` only — it does NOT accept `interval`. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/polymarket/open-interest","method":"GET","query":{"condition_id":"<string>","time_range":"<string>"}}'
```

### Polymarket orderbook history

Polymarket Orderbook History: Historical orderbook snapshots for a Polymarket token. Returns raw bid/ask depth levels. Timestamps in milliseconds.

Data refresh: ~5 minutes

`GET /gateway/v1/prediction-market/polymarket/orderbooks`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/b177b923-87cd-48fc-950f-c89b1c91ff19

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/polymarket-orderbooks

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `token_id` | string | Yes | Token identifier |
| `start_time` | integer | No | Start time in Unix milliseconds. 0 means 7 days ago. |
| `end_time` | integer | No | End time in Unix milliseconds. 0 means current time. |
| `limit` | integer | No | Maximum number of snapshots to return |
| `pagination_key` | string | No | Base64 cursor for pagination |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/polymarket/orderbooks","method":"GET","query":{"token_id":"<string>","start_time":"<integer>","end_time":"<integer>","limit":"<integer>","pagination_key":"<string>"}}'
```

### Polymarket wallet positions

Polymarket Wallet Positions: Given a specific wallet address, returns that wallet's open positions on Polymarket markets.

This is a single-wallet lookup — you must provide the wallet `address`.

**Not what you need?**
- To discover top/smart wallets across all of Polymarket, use `polymarket-smart-money` (view=positioning for aggregate signals, view=trades for individual whale trades).
- To find top traders by PnL or volume, use `polymarket-leaderboard`.

**Data refresh:** ~30 minutes

`GET /gateway/v1/prediction-market/polymarket/positions`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/12873730-54fa-445d-86dc-3937f7a61bfb

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/polymarket-positions

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Polymarket proxy wallet address |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/polymarket/positions","method":"GET","query":{"address":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Polymarket OHLCV candles

Polymarket OHLCV Candlesticks: OHLCV candlestick data for charting a Polymarket market — open, high, low, close, volume per candle.
Use this for rendering price charts with candlestick or bar visualizations.
For simple price time series (one price per interval), use `prices` instead.

Data refresh: ~30 minutes

`GET /gateway/v1/prediction-market/polymarket/price-ohlcv/{condition_id}`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/4033a9e0-0303-4d76-a3d5-279b8fd8ce72

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/polymarket-ohlcv

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `condition_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `start_time` | integer | No | Start time (Unix seconds). 0 means no lower bound. Cache aligns to 5-minute buckets, so two requests within the same bucket return the same cached result. |
| `end_time` | integer | No | End time (Unix seconds). 0 means current time. Cache aligns to 5-minute buckets, so two requests within the same bucket return the same cached result. |
| `interval` | integer | No | Candle interval in minutes: 1=1min, 60=1hour, 1440=1day |

```bash
# Replace {condition_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/polymarket/price-ohlcv/{condition_id}","method":"GET","query":{"start_time":"<integer>","end_time":"<integer>","interval":"<integer>"}}'
```

### Polymarket price history

Polymarket Price History: Simple price time series for a Polymarket market — one price point per interval.
Use this for tracking price trends over time.
For OHLCV candlestick data (open/high/low/close for charting libraries), use `price-ohlcv` instead.

**Data refresh:** ~30 minutes

`GET /gateway/v1/prediction-market/polymarket/prices`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/45134a3b-cd2d-4369-b9aa-fa72fce4d794

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/polymarket-prices

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `condition_id` | string | Yes | Market condition identifier |
| `time_range` | string | No | Window of history to return (how much data, from now backward): `7d`, `30d`, `90d`, `180d`, or `1y`. Ignored when `interval=latest`. Distinct from `interval` (which sets bucket size within this window). |
| `interval` | string | No | Bucket size for each point in the returned series: `1h` (hourly), `1d` (daily), or `latest` (single most-recent snapshot). Distinct from `time_range` (which sets the window size). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/polymarket/prices","method":"GET","query":{"condition_id":"<string>","time_range":"<string>","interval":"<string>"}}'
```

### Polymarket smart money

Polymarket Smart Money: Smart wallet analytics for Polymarket markets.

view=positioning (default): Aggregate smart wallet direction per market — net bullish/bearish signal and conviction.
view=trades: Individual $10K+ trades with wallet address, amount, outcome, price, and wallet age.

**Data refresh:** ~5 minutes

`GET /gateway/v1/prediction-market/polymarket/smart-money`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/b11110c8-e868-446e-bb67-79775cd3cdd2

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/polymarket-smart-money

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `view` | string | No | positioning = aggregate smart wallet direction per market; trades = individual $10K+ trades with wallet metadata |
| `condition_id` | string | No | Filter to a specific market (omit to browse all) |
| `category` | string | No | Filter by category |
| `direction` | string | No | Filter by net smart money direction (only for view=positioning) |
| `whale_tier` | string | No | Trade size tier filter (only for view=trades) |
| `from` | string | No | Start time as Unix seconds or date string (only for view=trades) |
| `to` | string | No | End time as Unix seconds or date string (only for view=trades) |
| `sort_by` | string | No | Sort field |
| `order` | string | No | Sort direction |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/polymarket/smart-money","method":"GET","query":{"view":"<string>","condition_id":"<string>","category":"<string>","direction":"<string>","whale_tier":"<string>","from":"<string>","to":"<string>","sort_by":"<string>","order":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Polymarket trades

Polymarket Trades: Trade and activity history for a Polymarket market or wallet.

Filter by market (condition_id), wallet (address), outcome (Yes/No), minimum trade size, and time range. Use type=redemption for splits/merges/redemptions, type=all for everything.

**Data refresh:** ~5 minutes

`GET /gateway/v1/prediction-market/polymarket/trades`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/7c26e557-aa6f-400e-8e00-9ea845c2fed6

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/polymarket-trades

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `condition_id` | string | No | Market condition identifier |
| `address` | string | No | Wallet address — returns trades where the address is maker or taker |
| `type` | string | No | Filter by activity type: `trade` (default, spot trades only), `redemption` (splits/merges/redemptions), or `all` (all activity). Use `redemption` or `all` to get non-trade wallet activity; `address` is required for these types. |
| `outcome_label` | string | No | Filter by outcome label: `Yes` or `No` |
| `min_amount` | number | No | Minimum trade amount in USD |
| `from` | string | No | Start of time range. Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`) |
| `to` | string | No | End of time range. Accepts Unix seconds (`1706745600`) or date string (`2024-02-01`) |
| `sort_by` | string | No | Field to sort results by |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/polymarket/trades","method":"GET","query":{"condition_id":"<string>","address":"<string>","type":"<string>","outcome_label":"<string>","min_amount":"<number>","from":"<string>","to":"<string>","sort_by":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Polymarket volume split

Polymarket Volume Split (YES/NO): Volume split by YES/NO outcome sides per interval (hour/day/week), plus total volume and trade count.
Use this to see directional volume bias.
For aggregate volume without YES/NO breakdown, use `volumes` instead.

Data refresh: ~30 minutes

`GET /gateway/v1/prediction-market/polymarket/volume-split/{condition_id}`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/358e3a91-c5aa-417a-8b64-625dc617dacc

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/polymarket-volume-split

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `condition_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `granularity` | string | No | Time granularity for volume aggregation |
| `start_time` | integer | No | Start time (Unix seconds). 0 means no lower bound. Cache aligns to 5-minute buckets, so two requests within the same bucket return the same cached result. |
| `end_time` | integer | No | End time (Unix seconds). 0 means current time. Cache aligns to 5-minute buckets, so two requests within the same bucket return the same cached result. |

```bash
# Replace {condition_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/polymarket/volume-split/{condition_id}","method":"GET","query":{"granularity":"<string>","start_time":"<integer>","end_time":"<integer>"}}'
```

### Polymarket volume history

Polymarket Volume History: Aggregate trading volume (USD) and trade count as a time series.
Use this for volume trend analysis.
For YES/NO volume breakdown by outcome side, use `volume-split` instead.

**Data refresh:** ~30 minutes

`GET /gateway/v1/prediction-market/polymarket/volumes`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/d72c5775-a272-4735-a200-0180f1ce652a

**Docs:** https://docs.asksurf.ai/data-api/prediction-market/polymarket-volumes

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `condition_id` | string | No | Market condition identifier (required if token_id not provided) |
| `token_id` | string | No | Token ID (alternative identifier, resolved to condition_id internally) |
| `time_range` | string | No | Window of history to return (how much data, from now backward): `7d`, `30d`, `90d`, `180d`, or `1y`. Distinct from `interval` (which sets bucket size within the window). |
| `interval` | string | No | Bucket size for each point in the returned series: `1h` (hourly) or `1d` (daily). Distinct from `time_range` (which sets the window size). |
| `granularity` | string | No | Aggregation granularity (alternative to interval). When provided, queries daily table with buy/sell volume breakdown. |
| `start_time` | integer | No | Start time as Unix seconds (alternative to time_range) |
| `end_time` | integer | No | End time as Unix seconds (alternative to time_range) |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/prediction-market/polymarket/volumes","method":"GET","query":{"condition_id":"<string>","token_id":"<string>","time_range":"<string>","interval":"<string>","granularity":"<string>","start_time":"<integer>","end_time":"<integer>"}}'
```

### Project AI news

Project AI News: AI-generated news and signal analysis for a project. Each item includes title, summary, TL;DR, signal type, and source URLs.

**Signal types returned:** `price_analysis`, `funding`. Social/X-derived items (`mindshare`, `twitter`, `ai_twitter`, items with tweet payloads or X/Twitter source URLs) are filtered out and never returned.

**Lookup:** by UUID (`id`) or name (`q`). Filter by `lang` (en/zh/ja/kr). Returns 404 if not found.

`GET /gateway/v1/project/ai-news`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/c3cc31ba-d1da-447d-b36d-1390bf23ae35

**Docs:** https://docs.asksurf.ai/data-api/project/ai-news

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Surf project UUID. PREFERRED — always use this when available from a previous response (e.g. project_id from /fund/portfolio or id from /search/project). Takes priority over q. |
| `q` | string | No | Fuzzy entity name search. Only use when 'id' is not available. May return unexpected results for ambiguous names. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |
| `lang` | string | No | Language for AI-generated content |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/project/ai-news","method":"GET","query":{"id":"<string>","q":"<string>","limit":"<integer>","offset":"<integer>","lang":"<string>"}}'
```

### DeFi protocol metrics

Project DeFi Metrics: Returns historical time-series for a single DeFi protocol metric (e.g. daily TVL). Each data point has a Unix timestamp and value.

**Available metrics:** `volume`, `fee`, `fees`, `revenue`, `tvl`, `users`.

**Lookup:** by UUID (`id`) or name (`q`). Filter by `chain` and date range (`from`/`to`). Returns 404 if the project is not found.

**Pagination:** check `meta.has_more`; when true, increase `offset` or `limit` to fetch the remaining points.

**Note:** this endpoint only returns data for DeFi protocol projects (e.g. `aave`, `uniswap`, `lido`, `makerdao`). Use `q` with a DeFi protocol name.

`GET /gateway/v1/project/defi/metrics`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/e9bd10bd-6769-48bf-8d74-14937fccf60c

**Docs:** https://docs.asksurf.ai/data-api/project/defi-metrics

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Surf project UUID. PREFERRED — always use this when available from a previous response (e.g. project_id from /fund/portfolio or id from /search/project). Takes priority over q. |
| `q` | string | No | Fuzzy entity name search. Only use when 'id' is not available. May return unexpected results for ambiguous names. |
| `metric` | string | No | Metric to query. Can be `volume`, `fees` (or `fee` alias), `revenue`, `tvl`, or `users`. Defaults to tvl. |
| `from` | string | No | Start of time range. Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`) |
| `to` | string | No | End of time range. Accepts Unix seconds (`1706745600`) or date string (`2024-02-01`) |
| `chain` | string | No | Filter by chain. Can be `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `base`, `avalanche`, `fantom`, or `solana`. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/project/defi/metrics","method":"GET","query":{"id":"<string>","q":"<string>","metric":"<string>","from":"<string>","to":"<string>","chain":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### DeFi protocol ranking

DeFi Protocol Ranking: Returns a DeFi protocol leaderboard (e.g. Aave, Uniswap, Lido) ranked by TVL, fees, revenue, or users. For individual pool/vault yields, use `onchain-yield-ranking` instead.

**Available metrics:** `tvl`, `revenue`, `fees`, `volume`, `users`.

`GET /gateway/v1/project/defi/ranking`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/311def91-1746-49a8-a9b5-c7788612e2aa

**Docs:** https://docs.asksurf.ai/data-api/project/defi-ranking

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `metric` | string | Yes | Ranking metric. Can be `tvl`, `revenue`, `fees`, `volume`, or `users`. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/project/defi/ranking","method":"GET","query":{"metric":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Crypto project detail

Aggregated Project Detail: Returns a crypto project's profile with selectable sub-resources: overview (description, chains, exchanges), token_info (price, market cap, supply, all-time high/low dates), tokenomics, funding, team, contracts, social, tge_status.

**Available fields** (via `fields`): `overview`, `token_info`, `tokenomics`, `funding`, `team`, `contracts`, `social`, `tge_status`.

**Important:** `tokenomics` is a legacy supply/valuation group (`total_supply`, `circulating_supply`, `market_cap_usd`, `fdv`). It does not include token unlock schedule, allocation, or unlock percentage data. For unlock schedule and unlocked-supply percentage, use `/token/tokenomics`.

**Lookup:** accepts project names directly via `q` (e.g. `?q=aave`) — no need to call `/search/project` first. Also accepts UUID via `id`. Returns 404 if not found.

For DeFi metrics (TVL, fees, revenue, volume, users) and per-chain breakdown, use `/project/defi/metrics`.

`GET /gateway/v1/project/detail`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/2ebf0178-4ff1-41eb-89b9-770b7cb17946

**Docs:** https://docs.asksurf.ai/data-api/project/detail

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Surf project UUID. PREFERRED — always use this when available from a previous response (e.g. project_id from /fund/portfolio or id from /search/project). Takes priority over q. |
| `x_id` | string | No | Numeric X (Twitter) account ID. Resolves to the associated project. |
| `handle` | string | No | X (Twitter) handle without @. Resolves to the associated project via twitter account lookup. |
| `q` | string | No | Fuzzy entity name search. Only use when 'id' is not available. May return unexpected results for ambiguous names. |
| `fields` | string | No | Comma-separated sub-resources to include. Can be `overview`, `token_info`, `tokenomics`, `funding`, `team`, `contracts`, `social`, or `tge_status`. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/project/detail","method":"GET","query":{"id":"<string>","x_id":"<string>","handle":"<string>","q":"<string>","fields":"<string>"}}'
```

### Tokenized asset catalog

Tokenized Asset Catalog: Discover stablecoins and tokenized stocks, funds and commodities. Resolve an ambiguous symbol here and pass the chosen rwa_asset_id to /rwa/metrics. Use a Surf token_id from token or equity data to find products by contract. With token_id, chain filters matched deployments. Each product lists all deployments, with token_id only on matches. Unknown query parameters and conflicting asset IDs return 422.

`GET /gateway/v1/rwa/assets`

**Cost:** Up to $0.03924 per call. Response-based: the price is worked out from the usage reported in the response, never more than $0.03924 per call. You aren't charged for failed calls. A wallet payment for a failed call is refunded.
- If you pay with a wallet (x402, MPP or Nanopayments), you pay this request's price before the call, not the final price from the response

Use `"dryRun": true` in the Run API request to see a request's price before calling.

**Page:** https://www.orthogonal.com/api/surf/53bb7252-1392-4507-86a2-d5b08df04625

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `rwa_asset_id` | string | No | RWA asset UUID returned by /rwa/assets. Identifies a product across its deployments. |
| `token_id` | string | No | Surf token UUID from a token or equity lookup. Matches the token by chain and contract address. |
| `asset_class` | string | No | Filter by primary asset class. |
| `symbol` | string | No | Exact token ticker, case-insensitive. |
| `q` | string | No | Substring of the token name or ticker. |
| `chain` | string | No | Filter by a deployment chain listed in this catalog. |
| `limit` | integer | No | Assets per page. |
| `offset` | integer | No | Assets to skip. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/rwa/assets","method":"GET","query":{"rwa_asset_id":"<string>","token_id":"<string>","asset_class":"<string>","symbol":"<string>","q":"<string>","chain":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Tokenized asset metrics

Tokenized Asset Daily Metrics: Use for daily market cap, holders and activity of one tokenized product. A unique symbol (e.g. USDC on solana) works directly. Resolve ambiguous symbols via /rwa/assets and pass rwa_asset_id. With a Surf token_id, add chain to narrow the request. Metrics require the registered token contracts and one product's catalog deployments to match exactly in scope. A partial or ambiguous match returns 422 with candidate product UUIDs. To request the product aggregate, use rwa_asset_id alone or with chain. A chain and address together select the entire product on that chain, including other share classes or deployments of that product there. Use /stablecoin/metrics for ordinary transfers excluding zero-address mints and burns on covered chains. Unknown query parameters and conflicting asset IDs return 422.

`GET /gateway/v1/rwa/metrics`

**Cost:** Up to $0.03924 per call. Response-based: the price is worked out from the usage reported in the response, never more than $0.03924 per call. You aren't charged for failed calls. A wallet payment for a failed call is refunded.
- If you pay with a wallet (x402, MPP or Nanopayments), you pay this request's price before the call, not the final price from the response

Use `"dryRun": true` in the Run API request to see a request's price before calling.

**Page:** https://www.orthogonal.com/api/surf/67a439f9-cd45-4810-a143-290cd25e3816

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `rwa_asset_id` | string | No | RWA asset UUID returned by /rwa/assets. Identifies a product across its deployments. |
| `token_id` | string | No | Surf token UUID from a token or equity lookup. Matches the token by chain and contract address. |
| `id` | string | No | Legacy alias of rwa_asset_id. Both UUIDs must agree when supplied together. |
| `symbol` | string | No | Exact token ticker. Use rwa_asset_id to select a product with an ambiguous ticker. |
| `address` | string | No | Deployment address identifying the asset. Requires chain. Metrics cover the selected chain. |
| `asset_class` | string | No | Narrow the asset lookup to one class. |
| `chain` | string | No | Limit the series to a deployment chain listed in the catalog. |
| `group_by` | string | No | One daily observation per asset or per asset and chain. |
| `from` | string | No | Inclusive UTC day. Accepts a date or a midnight timestamp. Defaults to 30 days ago. |
| `to` | string | No | Exclusive UTC day. Defaults to today. Maximum range is 366 days. |
| `limit` | integer | No | Observations per page. |
| `offset` | integer | No | Observations to skip. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/rwa/metrics","method":"GET","query":{"rwa_asset_id":"<string>","token_id":"<string>","id":"<string>","symbol":"<string>","address":"<string>","asset_class":"<string>","chain":"<string>","group_by":"<string>","from":"<string>","to":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Airdrop search

Airdrop Search: Searches and filters airdrop opportunities.

**Filters:** keyword, status, reward type, task type.

Returns paginated results with optional task details.

`GET /gateway/v1/search/airdrop`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/ad58f432-5c10-4c74-9211-40a351c179f2

**Docs:** https://docs.asksurf.ai/data-api/search/airdrop

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | No | Search keyword for coin name |
| `phase` | string | No | Comma-separated lifecycle phases. `active` = tasks open, can participate (POTENTIAL + CONFIRMED). `claimable` = eligible, can claim (SNAPSHOT + VERIFICATION + REWARD_AVAILABLE). `completed` = done (DISTRIBUTED). Defaults to `active,claimable` to show actionable airdrops. |
| `reward_type` | string | No | Filter by reward type |
| `task_type` | string | No | Filter activities containing tasks of this type |
| `has_open` | boolean | No | Only return activities with currently OPEN tasks |
| `sort_by` | string | No | Field to sort results by |
| `order` | string | No | Sort order |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |
| `include_tasks` | boolean | No | Include full task list per activity |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/search/airdrop","method":"GET","query":{"q":"<string>","phase":"<string>","reward_type":"<string>","task_type":"<string>","has_open":"<boolean>","sort_by":"<string>","order":"<string>","limit":"<integer>","offset":"<integer>","include_tasks":"<boolean>"}}'
```

### Airdrop activities

Airdrop Activities: Lists airdrop activities with pagination.

Returns activity metadata including reward type, status, and social metrics.

`GET /gateway/v1/search/airdrop/activities`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/960c8fb1-dfec-4b71-ac9e-9b17db3429cf

**Docs:** https://docs.asksurf.ai/data-api/search/airdrop-activities

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/search/airdrop/activities","method":"GET","query":{"limit":"<integer>","offset":"<integer>"}}'
```

### Project event search

Project Event Search: Searches project events by keyword, optionally filtered by `type`.

**Valid types:** `launch`, `upgrade`, `partnership`, `news`, `airdrop`, `listing`, `twitter`.

**Lookup:** by UUID (`id`) or name (`q`). Returns 404 if the project is not found.

`GET /gateway/v1/search/events`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/eeed276f-8b2d-4800-bf1f-77dee148b33f

**Docs:** https://docs.asksurf.ai/data-api/search/events

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Surf project UUID. PREFERRED — always use this when available from a previous response (e.g. project_id from /fund/portfolio or id from /search/project). Takes priority over q. |
| `q` | string | No | Fuzzy entity name search. Only use when 'id' is not available. May return unexpected results for ambiguous names. |
| `type` | string | No | Filter by event type. Can be `launch`, `upgrade`, `partnership`, `news`, `airdrop`, `listing`, or `twitter`. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/search/events","method":"GET","query":{"id":"<string>","q":"<string>","type":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Fund search

Fund Search: Searches funds by keyword.

**Included fields:** name, tier, type, logo, top invested projects.

`GET /gateway/v1/search/fund`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/5568f406-aa78-46c1-901a-ed93903e8e72

**Docs:** https://docs.asksurf.ai/data-api/search/fund

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | Yes | Search keyword — fund name like `a16z`, `paradigm`, or `coinbase ventures` |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/search/fund","method":"GET","query":{"q":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Fundraising search

Fundraising Event Search: Searches source-backed fundraising and token-sale events, or returns the latest fundraising timeline when `q` is omitted.

Supports inclusive UTC time bounds, source and importance filters, localization, deterministic sorting, and offset pagination. Results intentionally omit project or fundraiser identity because source context is not guaranteed to identify the organization raising funds.

`GET /gateway/v1/search/fundraising`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/a59b4825-817d-46e4-b18e-8b194bf83d7f

**Docs:** https://docs.asksurf.ai/data-api/search/fundraising

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | No | Optional project name, alias, symbol, title, or summary search query. When provided, the trimmed query must contain 2-100 Unicode characters. |
| `from` | string | No | Inclusive event-time lower bound. Accepts Unix seconds, YYYY-MM-DD, or RFC3339; date-only values start at 00:00:00 UTC. |
| `to` | string | No | Inclusive event-time upper bound. Accepts Unix seconds, YYYY-MM-DD, or RFC3339; date-only values end at 23:59:59 UTC. Defaults to the current time. |
| `source` | string | No | Filter by public source type: social or news. |
| `lang` | string | No | Display and search language. Missing translated fields fall back to English. ko is accepted as an alias for kr. |
| `min_importance` | integer | No | Minimum importance score from 1 to 5. Omit to include unscored events. |
| `sort_by` | string | No | Sort by recency, query relevance, or importance. Relevance requires q. |
| `order` | string | No | Sort order. Relevance only supports desc. |
| `limit` | integer | No | Results per page. |
| `offset` | integer | No | Pagination offset. The offset plus limit cannot exceed 10000. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/search/fundraising","method":"GET","query":{"q":"<string>","from":"<string>","to":"<string>","source":"<string>","lang":"<string>","min_importance":"<integer>","sort_by":"<string>","order":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### News search

News Article Search: Searches crypto news articles by keyword.

Returns results ranked by relevance (default) or newest first (`sort_by=recency`), with highlighted matching fragments. Optional `from` / `to` bound the publish time; a poller watching a keyword should pass `sort_by=recency` and `from=<last seen published_at>`. Supports pagination via limit and offset.

`GET /gateway/v1/search/news`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/91f26493-d2b4-41eb-b697-47759be5e5f9

**Docs:** https://docs.asksurf.ai/data-api/search/news

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | Yes | Search keyword or phrase |
| `from` | string | No | Filter articles published on or after this time. Accepts Unix seconds or date string (2024-01-01) |
| `to` | string | No | Filter articles published on or before this time. Accepts Unix seconds or date string (2024-02-01) |
| `sort_by` | string | No | Sort order: relevance (best match first) or recency (newest first). Pollers watching a keyword should use recency with from set to their last seen published_at |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/search/news","method":"GET","query":{"q":"<string>","from":"<string>","to":"<string>","sort_by":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Prediction market search

Search Prediction Markets: Browse and search prediction markets across all supported platforms.

Filter by platform, category, status, keyword search, and smart money direction. Each result includes volume, open interest, trade counts, and smart money signals.

Supports single-market lookup via `condition_id` or `market_ticker`.

**Data refresh:** ~5 minutes.

`GET /gateway/v1/search/prediction-market`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/aba738cf-1f36-4789-b37a-9421c31d16a3

**Docs:** https://docs.asksurf.ai/data-api/search/prediction-market

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `condition_id` | string | No | Polymarket condition ID for single-market lookup |
| `market_ticker` | string | No | Kalshi market ticker for single-market lookup |
| `platform` | string | No | Filter by platform (omit for both) |
| `category` | string | No | Filter by Surf-curated category |
| `status` | string | No | Market status filter |
| `sort_by` | string | No | Sort field |
| `order` | string | No | Sort direction |
| `smart_money` | string | No | Filter by smart money direction (Polymarket only) |
| `q` | string | No | Search markets by keyword in question text or ticker. Results include slug and event fields when available, but machine slugs are not searched. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/search/prediction-market","method":"GET","query":{"condition_id":"<string>","market_ticker":"<string>","platform":"<string>","category":"<string>","status":"<string>","sort_by":"<string>","order":"<string>","smart_money":"<string>","q":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Project search

Project Search: Searches crypto projects by keyword.

**Included fields:** name, description, chains, logo.

`GET /gateway/v1/search/project`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/4e9d225d-0d0c-4b29-9dee-8cc39fe3addb

**Docs:** https://docs.asksurf.ai/data-api/search/project

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | Yes | Search keyword — project name or ticker like `uniswap`, `bitcoin`, or `ETH` |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/search/project","method":"GET","query":{"q":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Token symbol lookup

Token Symbol Resolution: Resolves an exact token ticker symbol to likely contract address candidates on supported chains.

Use this before calling token endpoints that require a contract address. Pass a returned `chain` + `address` only to endpoints that support that chain.

Results are ranked by Surf registry, listing, and market signals. `volume_usd` is kept for response compatibility, always returns `0`, and must not be used as a candidate ordering signal.

**Included fields:** symbol, chain, address, decimals, volume_usd.

**Chains:** Ethereum, Base, BSC, Arbitrum, Solana, Polygon, Optimism, Avalanche, Fantom, Tron, Linea, Mantle, Blast, Gnosis, zkSync, Scroll.

`GET /gateway/v1/search/token`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/63d5f98d-46b1-4107-9470-d5aa04bde2b7

**Docs:** https://docs.asksurf.ai/data-api/search/token

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | Yes | Exact token ticker symbol to resolve (case-insensitive), like `USDC` or `PEPE`. NOT a contract address, trading pair, or fuzzy token name. |
| `chain` | string | No | Restrict resolution to one supported chain. Omit to search all supported chains. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/search/token","method":"GET","query":{"q":"<string>","chain":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Wallet search

Wallet Search: Searches wallets by ENS name, address label, or address prefix.

Returns matching wallet addresses with entity labels.

`GET /gateway/v1/search/wallet`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/e4c9657e-3363-4733-b5e2-bc7ee5540d04

**Docs:** https://docs.asksurf.ai/data-api/search/wallet

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | Yes | Search keyword like `binance`, `vitalik.eth`, or `0xd8dA...` |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/search/wallet","method":"GET","query":{"q":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Web search

Web Search: Searches web pages, articles, and content by keyword.

**Filters:** domain via `site` (e.g. `coindesk.com`).

**Included fields:** titles, URLs, content snippets.

`GET /gateway/v1/search/web`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/4b36af92-2f99-42b1-b12f-f790a9175b64

**Docs:** https://docs.asksurf.ai/data-api/search/web

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | Yes | Search query like `bitcoin price prediction 2026` |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |
| `site` | string | No | Comma-separated domain filter like `coindesk.com` or `cointelegraph.com` |
| `include_content` | boolean | No | When false (default), search returns title/url/description only — fast (~2-3s) URL discovery. Set true to also include full markdown content for each result (~5-30KB per result, ~10-15s for limit=5). Use true only when the caller needs page content inline and won't follow up with `/web/fetch`. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/search/web","method":"GET","query":{"q":"<string>","limit":"<integer>","offset":"<integer>","site":"<string>","include_content":"<boolean>"}}'
```

### Smart money flow summary

Smart Money Flow Summary: Whole-market totals of KOL trading: are KOLs net buying or net selling overall?

One row per market, window and scope: `market=spot` (on-chain DEX buys / sells) or `perp` (perpetual futures longs / shorts); `time_range` `3d`, `7d`, `30d` or `90d`; `scope=all` (every KOL on the composite board) or `smart` (the Smart KOLs among them). Each row carries the totals, the net flow, and how many KOLs and tokens were traded. Omit a filter to get every value.

Use `smart-money-token-flows` for the per-token boards behind these totals.

**Privacy:** responses never include wallet addresses or transaction identifiers. Amounts are rounded to 2 significant figures.

**Data refresh:** daily

`GET /gateway/v1/smart-money/flow/summary`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/bf8f70eb-d582-4091-ac4f-4c7e8f121a56

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `market` | string | No | Restrict to one market: spot (on-chain DEX) or perp (perpetual futures). Both when omitted |
| `time_range` | string | No | Restrict to one window. All windows when omitted |
| `scope` | string | No | Restrict to one scope: all (every KOL on the composite board) or smart (the Smart KOLs among them). Both when omitted |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/flow/summary","method":"GET","query":{"market":"<string>","time_range":"<string>","scope":"<string>"}}'
```

### FOMO trader comments

Smart Money FOMO Comments: What FOMO traders write on their own trades (their thesis), newest first: comment text, token, the token's price and market cap when it was written, likes / reposts / views, and whether the trade is still open.

Filter by trader (`handle`), token (`chain` + `address`, or `symbol`) and window (`time_range`: `1d`, `7d` default, `30d`). Without filters it is the latest comments across FOMO.

**Privacy:** only active, public FOMO accounts are served. Responses never include wallet addresses, transaction identifiers or FOMO's internal ids; a trader's USD amounts are rounded to 2 significant figures and trade dates are day-level; address-like text in comments is replaced with `[address]`.

**Data refresh:** hourly

`GET /gateway/v1/smart-money/fomo/comments`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/bface4c7-5f52-4983-8d1d-a3af501d85e5

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | No | Only this FOMO trader's comments (case-insensitive; @ and a fomo: prefix are optional) |
| `chain` | string | No | Only comments on tokens of this chain; required with address |
| `address` | string | No | Only comments on this token contract (needs chain) |
| `symbol` | string | No | Only comments on tokens with this symbol (case-insensitive, $ optional) |
| `time_range` | string | No | How far back |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/fomo/comments","method":"GET","query":{"handle":"<string>","chain":"<string>","address":"<string>","symbol":"<string>","time_range":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### FOMO trending tokens

Smart Money FOMO Tokens: Tokens FOMO traders are talking about: ranked by how many distinct traders commented on their trades in the token over `time_range` (`1d` default, `7d`), then by comments. Rows carry comment and engagement counts and the market cap at the latest comment. The list holds the top 200.

Use `smart-money-fomo-comments` with `chain` + `address` to read the comments.

**Privacy:** only active, public FOMO accounts are served. Responses never include wallet addresses, transaction identifiers or FOMO's internal ids; a trader's USD amounts are rounded to 2 significant figures and trade dates are day-level; address-like text in comments is replaced with `[address]`.

**Data refresh:** hourly

`GET /gateway/v1/smart-money/fomo/tokens`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/aac1298b-703a-4f75-ab96-5d9c2fe28828

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `time_range` | string | No | Window the comments are counted over |
| `chain` | string | No | Only tokens of this chain |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset (the list holds the top 200) |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/fomo/tokens","method":"GET","query":{"time_range":"<string>","chain":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### FOMO trader profile

Smart Money FOMO Trader: One FOMO trader: public profile and stats, Smart Money standing, recent trades (positions opened in `time_range` plus the ones still open, newest first, up to 50 — cost, realized / unrealized PnL, ROI and the trader's comment on the trade) and recent comments (up to 20).

Look up by FOMO handle (`@` and a `fomo:` prefix are optional). Returns 404 when there is no such public account.

**Privacy:** only active, public FOMO accounts are served. Responses never include wallet addresses, transaction identifiers or FOMO's internal ids; a trader's USD amounts are rounded to 2 significant figures and trade dates are day-level; address-like text in comments is replaced with `[address]`.

**Data refresh:** hourly

`GET /gateway/v1/smart-money/fomo/trader`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/41b264a5-8b4f-453d-b9b5-6cf7dda64197

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | Yes | FOMO handle (case-insensitive; @ and a fomo: prefix are optional) |
| `time_range` | string | No | Window for recent trades and comments, today included |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/fomo/trader","method":"GET","query":{"handle":"<string>","time_range":"<string>"}}'
```

### FOMO trader list

Smart Money FOMO Traders: Ranks traders on FOMO (the social trading app) by `sort_by`: `volume` (total traded on FOMO, default), `followers`, `trades` or `portfolio` (current value), among traders whose latest FOMO trade is within `time_range` (`7d`, `30d` default, `90d`, or `all` to include inactive ones). Each row is the trader's public FOMO profile and stats, plus `smart_money` — their standing on the Smart Money boards — when they are scored (as an X KOL linked to the account, or as `fomo:<handle>`). The list holds the top 500 per sort and window.

Use `smart-money-fomo-trader` for one trader's trades and comments.

**Privacy:** only active, public FOMO accounts are served. Responses never include wallet addresses, transaction identifiers or FOMO's internal ids; a trader's USD amounts are rounded to 2 significant figures and trade dates are day-level; address-like text in comments is replaced with `[address]`.

**Data refresh:** hourly

`GET /gateway/v1/smart-money/fomo/traders`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/52bdca5f-451a-4e2f-88e5-fb06a6e965c3

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sort_by` | string | No | Sort field (descending): volume (total traded on FOMO), followers, trades (number of trades), portfolio (current value) |
| `time_range` | string | No | Only traders whose latest FOMO trade is within this window; all: every trader, including inactive ones |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset (the list holds the top 500) |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/fomo/traders","method":"GET","query":{"sort_by":"<string>","time_range":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### KOL activity

Smart Money KOL Activity: Lists what KOLs opened and closed, one row per KOL, day, market, chain, token and kind (`open`, `close`), newest first: size (perp: notional), realized PnL on closes, and the number of positions behind the row. Covers the last 90 days.

Pass up to 50 X handles in `handles` (comma-separated, `@` optional, case-insensitive); a former handle is answered under the KOL's current one. `since` defaults to 7 days ago; `min_usd` (default 1000) drops small rows; `market` is `spot`, `perp` or `all`. The response also carries `coverage` for every requested handle.

**Privacy:** responses never include wallet addresses or transaction identifiers. Per-KOL amounts are rounded to 2 significant figures, and per-token KOL lists carry names only. Activity is aggregated per day.

**Data refresh:** hourly

`GET /gateway/v1/smart-money/kol/activity`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/181792f8-e932-4389-96a8-03d96fffedb5

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handles` | string | Yes | Comma-separated X/Twitter handles (with or without @, case-insensitive, at most 50) |
| `since` | string | No | Earliest day to include: Unix seconds or YYYY-MM-DD (UTC). Defaults to 7 days ago; anything older than 90 days is raised to 90 days ago |
| `min_usd` | number | No | Minimum size in USD (perp: notional) of a row |
| `market` | string | No | spot (on-chain DEX), perp (perpetual futures) or all |
| `limit` | integer | No | Rows per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/kol/activity","method":"GET","query":{"handles":"<string>","since":"<string>","min_usd":"<number>","market":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### KOL token coverage

Smart Money KOL Coverage: Says whether KOLs are tracked and scored: number of tracked wallets (shown up to 10), chains, latest trade day, last sync, sync tier, boards, and why a tracked KOL is not scored (`no_tracked_wallets`, `inactive_90d`, `insufficient_sample`).

Pass up to 50 X handles in `handles` (comma-separated, `@` optional, case-insensitive); a former handle is answered under the KOL's current one. Returns one entry per requested handle in request order; a handle that is not tracked gets `tracked: false` and nulls, never a 404.

**Privacy:** responses never include wallet addresses or transaction identifiers. Per-KOL amounts are rounded to 2 significant figures, and per-token KOL lists carry names only.

**Data refresh:** hourly

`GET /gateway/v1/smart-money/kol/coverage`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/1fa43b74-d0e1-49a4-b7a1-16e330c59481

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handles` | string | Yes | Comma-separated X/Twitter handles (with or without @, case-insensitive, at most 50) |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/kol/coverage","method":"GET","query":{"handles":"<string>"}}'
```

### KOL detail

Smart Money KOL Detail: Returns one KOL's smart-money profile: scores, board membership, per-market (spot / perp) statistics with weekly PnL, whether they hold what they call on X (big-account KOLs), and the KOLs they most often call the same tokens with.

Look up by X handle (a former handle works too), or by `fomo:<FOMO handle>` for a trader known only from FOMO. A KOL that is tracked but not scored gets its `coverage` and empty scores; returns 404 when the KOL is not tracked.

**Privacy:** responses never include wallet addresses or transaction identifiers. Per-KOL amounts are rounded to 2 significant figures, and per-token KOL lists carry names only.

**Data refresh:** daily

`GET /gateway/v1/smart-money/kol/detail`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/64b7db7b-4336-4abb-8f21-fee55e99f793

**Docs:** https://docs.asksurf.ai/data-api/smart-money/kol-detail

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | Yes | Trader handle (with or without @, case-insensitive): an X handle, or fomo:<handle> for a trader known only from FOMO |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/kol/detail","method":"GET","query":{"handle":"<string>"}}'
```

### KOL call history

Smart Money KOL History: A KOL's scores and board ranks day by day: one point per UTC day (the last published run of the day), oldest first.

Look up by X handle (a former handle works too), or by `fomo:<FOMO handle>` for a trader known only from FOMO. `time_range` is `7d`, `30d` (default) or `90d`; days without a published run are absent. Returns 404 when the KOL is not tracked.

**Privacy:** responses never include wallet addresses or transaction identifiers. Amounts are rounded to 2 significant figures.

**Data refresh:** daily

`GET /gateway/v1/smart-money/kol/history`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/081e1bfb-f5cf-4563-b7c0-908e62f5cb10

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | Yes | Trader handle (with or without @, case-insensitive): an X handle (a former handle works too), or fomo:<handle> for a trader known only from FOMO |
| `time_range` | string | No | How many days back, today included |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/kol/history","method":"GET","query":{"handle":"<string>","time_range":"<string>"}}'
```

### KOL holdings

Smart Money KOL Holdings: Returns KOLs' current portfolios in USD: total and DeFi value, the largest token holdings with their share of the total (stablecoins combined as `STABLES`), and open perp positions by notional. USD values only, never token amounts.

Pass up to 50 X handles in `handles` (comma-separated, `@` optional, case-insensitive); a former handle is answered under the KOL's current one. `min_usd` (default 500) drops small holdings; `limit` caps holdings per KOL.

**Privacy:** responses never include wallet addresses or transaction identifiers. Per-KOL amounts are rounded to 2 significant figures, and per-token KOL lists carry names only.

**Data refresh:** hourly

`GET /gateway/v1/smart-money/kol/holdings`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/2e05d3e4-6259-4b20-9fca-7627b3b5bc65

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handles` | string | Yes | Comma-separated X/Twitter handles (with or without @, case-insensitive, at most 50) |
| `min_usd` | number | No | Minimum USD value of a holding or perp position |
| `limit` | integer | No | Token holdings (and perp positions) per KOL |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/kol/holdings","method":"GET","query":{"handles":"<string>","min_usd":"<number>","limit":"<integer>"}}'
```

### KOL ranking

Smart Money KOL Ranking: Ranks crypto KOLs by how well they actually trade.

**Boards** (`type`):
- `composite` (default): trading skill blended with influence; every Smart KOL is included, plus KOLs with a composite score of at least 40.
- `smart`: trading skill only. The skill score is computed from the last 90 days of on-chain spot and perp positions and validated out of sample — KOLs scoring 75+ were profitable in the following month more than twice as often as the average KOL.
- `bigv`: large accounts (50k+ followers and $500k+ traded), regardless of skill.

Each row carries scores, 90-day PnL and volume (rounded) and the reasons a KOL is kept off the Smart board (`flags`). Use `smart-money-kol-detail` for per-market statistics. The pool also scores traders known only from FOMO; their handle is `fomo:<FOMO handle>`.

**Privacy:** responses never include wallet addresses or transaction identifiers. Per-KOL amounts are rounded to 2 significant figures, and per-token KOL lists carry

`GET /gateway/v1/smart-money/kol/ranking`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/01ded0e8-c3ff-4515-bf30-fbd414a04cf9

**Docs:** https://docs.asksurf.ai/data-api/smart-money/kol-ranking

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | No | Board: composite (skill + influence), smart (trading skill only), bigv (large following and trading volume) |
| `sort_by` | string | No | Sort field. Defaults to the board's own order: rank for composite and smart (by unrounded scores), volume (spot + perp, unrounded) for bigv |
| `order` | string | No | Sort order |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/kol/ranking","method":"GET","query":{"type":"<string>","sort_by":"<string>","order":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Smart money token calls

Smart Money Token Calls: Ranks tokens by how many tracked KOLs called them bullish (on X, or in a comment on their own FOMO trade), and checks the calls against their positions: how many callers held the token when calling, who called first, how fast others followed, and the net flow of all tracked KOLs on the token.

`time_range` is `7d`, `30d` or `120d`. Major assets are excluded unless `include_majors=true`.

**Privacy:** responses never include wallet addresses or transaction identifiers. Per-KOL amounts are rounded to 2 significant figures, and per-token KOL lists carry names only.

**Data refresh:** daily

`GET /gateway/v1/smart-money/token/calls`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/76c10028-c9f6-4043-9146-76745b75b635

**Docs:** https://docs.asksurf.ai/data-api/smart-money/token-calls

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `time_range` | string | No | Window to count calls over |
| `include_majors` | boolean | No | Include major assets (BTC, ETH, SOL, ...) |
| `chain` | string | No | Restrict to tokens on one chain (canonical long-form names) |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/token/calls","method":"GET","query":{"time_range":"<string>","include_majors":"<boolean>","chain":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Smart money token consensus

Smart Money Token Consensus: Spot tokens KOLs are net buying, with two signals per token:

- `consensus`: broad buying — at least 3 KOLs are net buyers and the largest buyer accounts for less than 75% of the buying (not one whale).
- `called`: KOLs also called the token bullish on X or FOMO in the same window; `call` says how many, and how many of them held or bought it.

`signal` picks the tokens: `consensus` (default), `called`, or `both`. `time_range` is `7d` or `30d`. Rows follow the inflow board (largest net buying first) and carry the same flow fields as `smart-money-token-flows`.

**Privacy:** responses never include wallet addresses or transaction identifiers. Amounts are rounded to 2 significant figures. Per-token KOL lists carry names only.

**Data refresh:** daily

`GET /gateway/v1/smart-money/token/consensus`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/304808d7-3332-4f12-b82d-8e1ad554ac2e

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `time_range` | string | No | Window the flows and calls are computed over |
| `signal` | string | No | consensus: broad buying (at least 3 net buyers, largest buyer under 75%); called: net buying that KOLs also called bullish; both: both at once |
| `chain` | string | No | Restrict to one chain (canonical long-form names) |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/token/consensus","method":"GET","query":{"time_range":"<string>","signal":"<string>","chain":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Smart money token flows

Smart Money Token Flows: Ranks tokens by the net buying (`inflow`) or net selling (`outflow`) of the KOLs on the composite board.

- `market=spot`: on-chain DEX buys and sells across Solana, Ethereum, Base, BSC, Arbitrum, Robinhood Chain and more; filter with `chain`.
- `market=perp`: perpetual futures longs and shorts.

`time_range` is `3d`, `7d`, `30d` or `90d`. Rows include buyer / seller counts, buying concentration, token age and price change since the first KOL buy.

**Privacy:** responses never include wallet addresses or transaction identifiers. Per-KOL amounts are rounded to 2 significant figures, and per-token KOL lists carry names only.

**Data refresh:** daily

`GET /gateway/v1/smart-money/token/flows`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/7b4bd5e4-4f69-4ef3-be8d-688d15c5bc5a

**Docs:** https://docs.asksurf.ai/data-api/smart-money/token-flows

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `market` | string | No | spot (on-chain DEX buys/sells) or perp (perpetual futures longs/shorts) |
| `time_range` | string | No | Window to aggregate flows over |
| `direction` | string | No | inflow (net buying / net long) or outflow (net selling / net short) |
| `chain` | string | No | Spot only: restrict to one chain (canonical long-form names; covers every chain the Smart Money data has had so far) |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/token/flows","method":"GET","query":{"market":"<string>","time_range":"<string>","direction":"<string>","chain":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Smart money token tweets

Smart Money Token Tweets: Lists tracked KOLs' posts that call a token, newest first, with the call direction and the KOL's position at post time (`holding`, `bought_after`, `sold_before`, ...): tweets on X and comments on their own FOMO trades (`source`). Returns post references (ID, and URL for tweets), not post text.

Look up by token `symbol`. Unknown symbols return an empty list.

**Privacy:** responses never include wallet addresses or transaction identifiers. Per-KOL amounts are rounded to 2 significant figures, and per-token KOL lists carry names only.

**Data refresh:** daily

`GET /gateway/v1/smart-money/token/tweets`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/a07ecdb0-d36b-42ec-93fc-dcc3bfad656c

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `symbol` | string | Yes | Token symbol (case-insensitive) |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/smart-money/token/tweets","method":"GET","query":{"symbol":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Project mindshare series

Project Mindshare Time Series: Returns project social view-count time series, grouped by the required interval (5m, 1h, 1d, or 7d). Provide exactly one of id (Surf project UUID) or q (project name). Optional from/to accept Unix seconds or date strings; omitted to defaults to the current interval boundary, and omitted from defaults to 30 days before to. No pagination or time_range parameter. Source defaults to x; binance_square is also supported. Set include_tag_percents=true for per-tag percentage series and optional ranking snapshots. This measures attention, not sentiment.

`GET /gateway/v1/social/mindshare`

**Cost:** Up to $0.03924 per call. Response-based: the price is worked out from the usage reported in the response, never more than $0.03924 per call. You aren't charged for failed calls. A wallet payment for a failed call is refunded.
- If you pay with a wallet (x402, MPP or Nanopayments), you pay this request's price before the call, not the final price from the response

Use `"dryRun": true` in the Run API request to see a request's price before calling.

**Page:** https://www.orthogonal.com/api/surf/2bc580e2-8de3-4d80-9606-8797ae1a3618

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Surf project UUID. Provide one of `id` or `q`. |
| `q` | string | No | Entity name to resolve like `uniswap`, `ethereum`, or `aave`. Provide one of `id` or `q`. |
| `interval` | string | Yes | Bucket size for each point in the returned time-series: `5m`, `1h`, `1d`, or `7d`. This is NOT a window — the default window is 30 days; pass `from`/`to` to bound the range. Not the same parameter as `time_range` (which does not exist on this endpoint). Note: when `include_tag_percents=true`, `5m` falls back to hourly data for the per-tag series (Argus has no 5m granularity for tag percentages). |
| `from` | string | No | Start timestamp. Accepts Unix seconds (1704067200) or date string (2024-01-01) |
| `to` | string | No | End timestamp. Accepts Unix seconds (1706745600) or date string (2024-02-01) |
| `include_tag_percents` | boolean | No | Set to `true` to additionally return per-tag mindshare percentage time-series in the `tag_percents` field. A project can belong to multiple tags; each tag returns its own sparse time-series (values are 0~100 percentages, not ratios). Default `false` — response shape is byte-identical to the legacy format. |
| `source` | string | No | Data lane: `x` (X/Twitter, default) or `binance_square` (Binance Square). Response shape is identical across sources. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/social/mindshare","method":"GET","query":{"id":"<string>","q":"<string>","interval":"<string>","from":"<string>","to":"<string>","include_tag_percents":"<boolean>","source":"<string>"}}'
```

### Stablecoin registry

Covered Stablecoin Deployments: List deployments covered by the stablecoin transfer dataset. Discover tokenized products across chains with /rwa/assets. Use a returned rwa_asset_id on either family of endpoints. An uncovered rwa_asset_id returns 404. Unknown query parameters and conflicting asset IDs return 422.

`GET /gateway/v1/stablecoin/assets`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/ef5f3356-cca0-44dd-9a93-20d0825dadbc

**Docs:** https://docs.asksurf.ai/data-api/stablecoin/assets

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `rwa_asset_id` | string | No | RWA asset UUID returned by /rwa/assets. Identifies a product across its deployments. |
| `chain` | string | No | Optional chain. |
| `asset_id` | string | No | Legacy stablecoin slug (e.g. usdc). If also supplying rwa_asset_id, both must identify the same asset. |
| `symbol` | string | No | Deployment symbol, case-insensitive. |
| `limit` | integer | No | Results per page. |
| `offset` | integer | No | Rows to skip. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/stablecoin/assets","method":"GET","query":{"rwa_asset_id":"<string>","chain":"<string>","asset_id":"<string>","symbol":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Stablecoin daily metrics

Daily Stablecoin Transfers: Use for ordinary on-chain stablecoin transfers by UTC day. Zero-address mints and burns are excluded. Select a product with rwa_asset_id. Add chain and token_address for one deployment. Deployment rows report exact daily sending addresses. Use /rwa/metrics for market cap, holders, Solana or cross-chain market activity. An uncovered rwa_asset_id returns 404. Unknown query parameters and conflicting asset IDs return 422.

`GET /gateway/v1/stablecoin/metrics`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/eb61d9b5-2030-408e-9671-9039a301e32b

**Docs:** https://docs.asksurf.ai/data-api/stablecoin/metrics

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `rwa_asset_id` | string | No | RWA asset UUID returned by /rwa/assets. Identifies a product across its deployments. |
| `asset_id` | string | No | Legacy stablecoin slug (e.g. usdc). If also supplying rwa_asset_id, both must identify the same asset. |
| `chain` | string | No | Covered chain (case-insensitive): ethereum, base, arbitrum, bsc, hyperevm, robinhoodchain, tron or tempo. |
| `token_address` | string | No | Deployment address; requires chain. |
| `from` | string | No | Inclusive UTC date YYYY-MM-DD. |
| `to` | string | No | Exclusive UTC date YYYY-MM-DD. |
| `group_by` | string | No | One row per UTC day and deployment, or per day and asset. Only deployment rows report exact daily active_senders. |
| `limit` | integer | No | Results per page. |
| `offset` | integer | No | Rows to skip. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/stablecoin/metrics","method":"GET","query":{"rwa_asset_id":"<string>","asset_id":"<string>","chain":"<string>","token_address":"<string>","from":"<string>","to":"<string>","group_by":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Stablecoin overview

Period Stablecoin Transfer Totals and Rankings: Use for ordinary stablecoin transfer totals over a period or rankings across covered assets. Zero-address mints and burns are excluded. For a USD volume ranking use sort_by=transfer_volume_usd. Filter one asset with rwa_asset_id. Use /stablecoin/metrics for a daily series. An uncovered rwa_asset_id returns 404. Unknown query parameters and conflicting asset IDs return 422.

`GET /gateway/v1/stablecoin/overview`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/d49e1b16-7df0-4f9c-9020-1ff0900ef9cc

**Docs:** https://docs.asksurf.ai/data-api/stablecoin/overview

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `rwa_asset_id` | string | No | RWA asset UUID returned by /rwa/assets. Identifies a product across its deployments. |
| `asset_id` | string | No | Legacy stablecoin slug (e.g. usdc). If also supplying rwa_asset_id, both must identify the same asset. |
| `chain` | string | No | Covered chain (case-insensitive): ethereum, base, arbitrum, bsc, hyperevm, robinhoodchain, tron or tempo. |
| `token_address` | string | No | Deployment address; requires chain. |
| `from` | string | No | Inclusive UTC date YYYY-MM-DD. |
| `to` | string | No | Exclusive UTC date YYYY-MM-DD. |
| `sort_by` | string | No | Period ranking field. Use transfer_volume_usd for comparable amounts across different tokens. |
| `order` | string | No | Sort order. |
| `limit` | integer | No | Results per page. |
| `offset` | integer | No | Rows to skip. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/stablecoin/overview","method":"GET","query":{"rwa_asset_id":"<string>","asset_id":"<string>","chain":"<string>","token_address":"<string>","from":"<string>","to":"<string>","sort_by":"<string>","order":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Token DEX trades

Token DEX Trade History: Returns recent DEX swap events for a token contract address.

**Covered DEXes:** `uniswap`, `sushiswap`, `curve`, `balancer`, `pancakeswap` (and other major DEXes per chain).

**Included fields:** trading pair, amounts, USD value, taker address.

**Data refresh:** ~24 hours · **Chains:** Ethereum, Base, BSC, Arbitrum, Tron, Robinhood

`GET /gateway/v1/token/dex-trades`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/1a7f67e1-d3ed-49d1-ac37-a64caccacb12

**Docs:** https://docs.asksurf.ai/data-api/token/dex-trades

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Token CONTRACT ADDRESS — 0x-prefixed hex (EVM chains only; Tron also accepts base58 `T...`). This is NOT a ticker symbol (e.g. do NOT pass `USDC` or `BTC`). To resolve a ticker symbol to a contract address, call GET /v1/search/token?q={symbol}&chain={chain} and use the `address` whose `chain` is supported by this endpoint. This endpoint has no `symbol` parameter. |
| `chain` | string | No | Chain. Can be `ethereum`, `base`, `bsc`, `arbitrum`, `tron`, or `robinhood`. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |
| `include` | string | No | Comma-separated enrichments to attach to each trade. Currently valid: `labels` — adds a `taker_label` field with entity information for the taker address. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/token/dex-trades","method":"GET","query":{"address":"<string>","chain":"<string>","limit":"<integer>","offset":"<integer>","include":"<string>"}}'
```

### Token holders

Token Holders: Returns top token holders for a contract address.

**Included fields:** wallet address, balance, and percentage.

**Lookup:** by `address` and `chain`. Supports EVM chains and Solana.

`GET /gateway/v1/token/holders`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/46ec7b4a-bfc6-42ef-b7b0-b840e89b4e92

**Docs:** https://docs.asksurf.ai/data-api/token/holders

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Token CONTRACT ADDRESS — 0x-prefixed hex for EVM chains, base58 for Solana. This is NOT a ticker symbol (e.g. do NOT pass `USDC` or `BTC`). To resolve a ticker symbol to a contract address, call GET /v1/search/token?q={symbol}&chain={chain} and use the `address` whose `chain` is supported by this endpoint. This endpoint has no `symbol` parameter. |
| `chain` | string | Yes | Chain. Can be `ethereum`, `polygon`, `bsc`, `solana`, `avalanche`, `arbitrum`, `optimism`, or `base`. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |
| `include` | string | No | Comma-separated enrichments to attach to each holder. Currently valid: `labels` — adds a full `label` record alongside the flat `entity_name` / `entity_type` fields. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/token/holders","method":"GET","query":{"address":"<string>","chain":"<string>","limit":"<integer>","offset":"<integer>","include":"<string>"}}'
```

### Token unlock schedule

Token Unlock Schedule: Returns token unlock time-series with cumulative amounts, allocation breakdowns, total supply denominator, and unlocked-supply percentage.

**Lookup:** by project UUID (`id`) or token `symbol`. Filter by date range with `from`/`to` — defaults to the current calendar month when omitted.

**Important:** `unlock_amount` is a legacy alias for `cumulative_unlocked_amount`; it is already cumulative at each timestamp and must not be summed across rows. Use `unlocked_percentage_of_total_supply` for the unlock ratio.

Returns 404 if no token found.

`GET /gateway/v1/token/tokenomics`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/75f579e3-ce24-4fa1-acee-3d9d2c6b1b20

**Docs:** https://docs.asksurf.ai/data-api/token/tokenomics

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Surf project UUID. PREFERRED — always use this when available from a previous response. Takes priority over symbol. |
| `symbol` | string | No | Token symbol like `ARB`, `OP`, or `APT` |
| `from` | string | No | Start of time range. Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`) |
| `to` | string | No | End of time range. Accepts Unix seconds (`1735689600`) or date string (`2025-01-01`) |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/token/tokenomics","method":"GET","query":{"id":"<string>","symbol":"<string>","from":"<string>","to":"<string>"}}'
```

### Token transfer counterparties

Top Transfer Counterparties: Ranked top counterparties (receivers or senders) of a token over a window — answers "who are the top receivers/senders?".

**Lookup:** `address` (token contract) + `chain` + `direction` (`to` = top receivers, `from` = top senders). Rank by `metric` (`count`, `amount`, `amount_usd`).

**Related:** raw rows → `/v1/token/transfers`; aggregate summary → `/v1/token/transfer-stats`.

**Chains:** Ethereum, Base, BSC, Arbitrum, Tron · **Refresh:** ~24h

`GET /gateway/v1/token/transfer-counterparties`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/3e74f796-fc95-40db-ac6a-351b506f1496

**Docs:** https://docs.asksurf.ai/data-api/token/transfer-counterparties

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Token CONTRACT ADDRESS (0x-hex for EVM; Tron accepts base58 `T...` or 0x-hex). Not a ticker — resolve a symbol via GET /v1/search/token?q={symbol}&chain={chain} and use a returned address whose chain is supported by this endpoint. |
| `chain` | string | Yes | Chain the token contract is deployed on. |
| `direction` | string | Yes | Ranking direction: `to` = top receivers, `from` = top senders. |
| `metric` | string | No | Ranking key: `count` = transfer frequency, `amount` = decimal-adjusted token sum, `amount_usd` = USD value sum (USD lags ~3 days; unreliable for recent windows). |
| `time_range` | string | No | Look-back window (hard 90d cap). |
| `limit` | integer | No | Results per page. |
| `offset` | integer | No | Pagination offset. |
| `include` | string | No | Comma-separated enrichments. `labels` attaches an entity label per counterparty. |
| `exclude_labels` | string | No | Comma-separated entity categories to drop (best-effort): `cex`, `router`, `amm`, `bridge`. Results may be fewer than `limit` when top counterparties are infrastructure. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/token/transfer-counterparties","method":"GET","query":{"address":"<string>","chain":"<string>","direction":"<string>","metric":"<string>","time_range":"<string>","limit":"<integer>","offset":"<integer>","include":"<string>","exclude_labels":"<string>"}}'
```

### Token transfer stats

Token Transfer Activity Summary: Aggregate transfer-activity summary for a token over a window — total transfers, unique senders/receivers, total amount, first/last activity, and an optional daily series (`include=series`).

**Lookup:** `address` (token contract) + `chain`.

**Related:** per-counterparty ranking → `/v1/token/transfer-counterparties`; raw rows → `/v1/token/transfers`.

**Chains:** Ethereum, Base, BSC, Arbitrum, Tron · **Refresh:** ~24h · USD value lags ~3 days (see `enriched_ratio`).

`GET /gateway/v1/token/transfer-stats`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/b4e8aa31-826d-4116-827b-946b8784a1e9

**Docs:** https://docs.asksurf.ai/data-api/token/transfer-stats

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Token CONTRACT ADDRESS (0x-hex for EVM; Tron accepts base58 `T...` or 0x-hex). Not a ticker — resolve a symbol via GET /v1/search/token?q={symbol}&chain={chain} and use a returned address whose chain is supported by this endpoint. |
| `chain` | string | Yes | Chain the token contract is deployed on. |
| `time_range` | string | No | Look-back window (hard 90d cap). |
| `include` | string | No | Comma-separated extras. `series` adds a daily trend breakdown (volume only). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/token/transfer-stats","method":"GET","query":{"address":"<string>","chain":"<string>","time_range":"<string>","include":"<string>"}}'
```

### Token transfer history

Token Transfer History: Returns recent transfer events **for a specific token** (ERC-20/TRC-20 contract).

Pass the **token contract address** in `address` — returns every on-chain transfer of that token regardless of sender/receiver.

**Included fields:** sender, receiver, raw amount, block timestamp.

Use this to analyze a token's on-chain activity (e.g. large movements, distribution patterns).

**Lookup:** `address` (token contract) + `chain`. Sort by `asc` or `desc`.

**Data refresh:** ~24 hours · **Chains:** Ethereum, Base, BSC, Arbitrum, Tron (Solana uses a different source with no delay)

`GET /gateway/v1/token/transfers`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/d930c32a-87b7-414d-9e72-e7603dca2f43

**Docs:** https://docs.asksurf.ai/data-api/token/transfers

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Token CONTRACT ADDRESS — 0x-prefixed hex for EVM chains, base58 for Solana. This is NOT a ticker symbol (e.g. do NOT pass `USDC` or `BTC`). To resolve a ticker symbol to a contract address, call GET /v1/search/token?q={symbol}&chain={chain} and use the `address` whose `chain` is supported by this endpoint. This endpoint has no `symbol` parameter. |
| `chain` | string | Yes | Chain. Can be `ethereum`, `base`, `solana`, `tron`, `bsc`, or `arbitrum`. |
| `from` | string | No | Start of date range. Accepts Unix seconds or YYYY-MM-DD. Defaults to 7 days ago. |
| `to` | string | No | End of date range. Accepts Unix seconds or YYYY-MM-DD. Defaults to today. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |
| `include` | string | No | Comma-separated enrichments to attach to each transfer. Currently valid: `labels` — adds `from_label` and `to_label` fields. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/token/transfers","method":"GET","query":{"address":"<string>","chain":"<string>","from":"<string>","to":"<string>","limit":"<integer>","offset":"<integer>","include":"<string>"}}'
```

### Wallet detail

Aggregated Wallet Detail: Returns a wallet's cross-chain portfolio with selectable sub-resources (balance, tokens, labels, NFTs). Always includes per-chain USD breakdown across 15+ EVM chains.

**Available fields** (via `fields`): `balance`, `tokens`, `labels`, `nft`.

**Lookup:** by `address`. Partial failures return available fields with per-field error info. Returns 422 if `fields` is invalid.

`GET /gateway/v1/wallet/detail`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/d86b5503-4cf1-4292-ad30-9c098c18e040

**Docs:** https://docs.asksurf.ai/data-api/wallet/detail

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address (0x hex for EVM, base58 for Solana) |
| `chain` | string | No | Chain filter for `tokens`, `nft`, and `approvals`. When omitted, inferred from address format: 0x addresses query all EVM chains, base58 addresses query Solana. |
| `fields` | string | No | Comma-separated sub-resources to include. Valid: `balance`, `tokens`, `labels`, `nft`, `approvals`. The `active_chains` field is always returned. `approvals` is opt-in (not in default) as it triggers additional upstream calls. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/wallet/detail","method":"GET","query":{"address":"<string>","chain":"<string>","fields":"<string>"}}'
```

### Wallet transaction history

Wallet Transaction History: Returns all on-chain transactions for a wallet, classified by type (send, receive, swap, approve) with native token value. For ERC-20 token transfers with token identity and USD value, use `wallet-transfers` instead.

**Lookup:** by `address`. Filter by `chain` — supports `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `avalanche`, `fantom`, `base`.

`GET /gateway/v1/wallet/history`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/713a3c6d-0976-46f2-a48c-d4788a31ad18

**Docs:** https://docs.asksurf.ai/data-api/wallet/history

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address — must be a raw 0x-prefixed hex address, not an ENS name |
| `chain` | string | No | Chain filter. Can be `ethereum`, `polygon`, `bsc`, `avalanche`, `arbitrum`, `optimism`, `fantom`, or `base`. |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset. This feed is cursor-paginated upstream and only the most recent ~1000 transactions are reachable; a larger offset returns an empty page with meta.empty_reason rather than an error. For deep history prefer the `before` cursor — its upstream cost is bounded by `limit` and independent of depth, whereas a large offset is emulated by walking the whole feed. |
| `before` | integer | No | Cursor for efficient deep pagination: return transactions strictly older than this Unix-seconds timestamp (exclusive). Pass the `timestamp` of the last item from the previous page; if items may share a second, pass that timestamp + 1 and de-duplicate on `tx_hash`. Unlike `offset` (which walks the feed), the number of upstream fetches is bounded by `limit` (DeBank returns up to 20 per page) and independent of how far back you page. Mutually exclusive with `offset`. |
| `sort_by` | string | No | Field to sort results by. The cursor-paginated upstream feed only supports `timestamp` correctly; unsupported values are rejected by the handler for correctness. |
| `order` | string | No | Sort order. The cursor-paginated upstream feed only supports `desc` correctly; unsupported values are rejected by the handler for correctness. |
| `include` | string | No | Comma-separated enrichments to attach to each item. Currently valid: `labels` — adds `from_label` and `to_label` fields with entity information for each counterparty address. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/wallet/history","method":"GET","query":{"address":"<string>","chain":"<string>","limit":"<integer>","offset":"<integer>","before":"<integer>","sort_by":"<string>","order":"<string>","include":"<string>"}}'
```

### Wallet labels

Wallet Labels (Batch): Returns entity labels for multiple wallet addresses.

Pass up to 100 comma-separated addresses via the `addresses` query parameter.

**Included fields:** entity name, type, and labels per address.

`GET /gateway/v1/wallet/labels/batch`

**Cost:** $0.02616 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/4dcf7edb-9b89-470d-ac8b-16c7c91d70dd

**Docs:** https://docs.asksurf.ai/data-api/wallet/labels-batch

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `addresses` | string | Yes | Comma-separated wallet addresses to look up, max 100 |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/wallet/labels/batch","method":"GET","query":{"addresses":"<string>"}}'
```

### Wallet net worth history

Wallet Net Worth History: Returns a time-series of the wallet's total net worth in USD.

Returns ~288 data points at 5-minute intervals covering the last 24 hours. Fixed window — no custom time range supported.

**Lookup:** by `address` (EVM only — 0x-prefixed hex). Solana addresses are not supported.

`GET /gateway/v1/wallet/net-worth`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/7e79047e-1808-4d9e-b197-3cb7224a335a

**Docs:** https://docs.asksurf.ai/data-api/wallet/net-worth

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address — must be a raw 0x-prefixed hex address (EVM only). Solana and ENS names are not supported. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/wallet/net-worth","method":"GET","query":{"address":"<string>"}}'
```

### Wallet DeFi positions

Wallet DeFi Protocol Positions: Returns all DeFi protocol positions for a wallet — lending, staking, LP, and farming with token breakdowns and USD values.

**Lookup:** by `address` (EVM only — 0x-prefixed hex). Solana addresses are not supported.

`GET /gateway/v1/wallet/protocols`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/7640f2b6-7307-4bc0-9e6e-eb3bb5544fbe

**Docs:** https://docs.asksurf.ai/data-api/wallet/protocols

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address — must be a raw 0x-prefixed hex address, not an ENS name |
| `limit` | integer | No | Results per page |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/wallet/protocols","method":"GET","query":{"address":"<string>","limit":"<integer>","offset":"<integer>"}}'
```

### Wallet transfers

Wallet Transfer History: Returns ERC-20/SPL token transfers with token identity, USD value, and flow direction (in/out). Unlike `wallet-history` which shows all tx types in native value, this focuses on token-level transfer activity.

Pass the **wallet address** in `address` — returns all ERC-20/SPL token transfers where this wallet is the sender or receiver.

**Included fields:** token contract, token symbol, amount USD, counterparty, flow direction.

Filter by specific token or flow direction (in/out).

**Lookup:** `address` (wallet, raw 0x hex or base58 — ENS not supported). Filter by `chain` — supports `ethereum`, `base`, `bsc`, `arbitrum`, `tron`, `solana`.

**Data refresh:** ~24 hours · **Chains:** Ethereum, Base, BSC, Arbitrum, Tron (Solana uses a different source with no delay)

`GET /gateway/v1/wallet/transfers`

**Cost:** $0.01308 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/6e199178-c62d-432d-a754-58b234363fb2

**Docs:** https://docs.asksurf.ai/data-api/wallet/transfers

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Wallet address — must be a raw address (0x-prefixed hex for EVM, base58 for Solana). ENS names like `vitalik.eth` are not supported; resolve to a 0x address first. |
| `chain` | string | No | Chain. Can be `ethereum`, `base`, `solana`, `tron`, `bsc`, or `arbitrum`. |
| `flow` | string | No | Filter by transfer direction relative to the queried wallet. `in` for incoming, `out` for outgoing. Omit for both directions. |
| `token` | string | No | Filter by token contract address. Use `0x0000000000000000000000000000000000000000` for native token transfers. Omit for all tokens. |
| `limit` | integer | No | Results per page. Default 20, max 100. NOTE: Solana (`chain=solana`) is hard-capped at 40 per call by the upstream Solscan API — values above 40 return at most 40 items. Check `meta.has_more` and paginate with `offset` to fetch beyond the first page. |
| `offset` | integer | No | Pagination offset. For Solana, this maps to Solscan's 1-indexed `page` parameter (page = offset/page_size + 1). |
| `include` | string | No | Comma-separated enrichments to attach to each transfer. Currently valid: `labels` — adds `from_label` and `to_label` fields with entity information for each counterparty address. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/wallet/transfers","method":"GET","query":{"address":"<string>","chain":"<string>","flow":"<string>","token":"<string>","limit":"<integer>","offset":"<integer>","include":"<string>"}}'
```

### Web page fetch

Web Page Fetch: Fetches a web page and converts it to clean, LLM-friendly markdown.

**Options:**
- `target_selector` — extract specific page sections
- `remove_selector` — strip unwanted elements

Returns 400 if the URL is invalid or unreachable.

`GET /gateway/v1/web/fetch`

**Cost:** $0.00654 per call. Fixed: every call costs the same. You aren't charged for failed calls. A wallet payment for a failed call is refunded.

**Page:** https://www.orthogonal.com/api/surf/0ff8c12d-39de-419e-bd31-eb780637855b

**Docs:** https://docs.asksurf.ai/data-api/web/fetch

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | URL to fetch and parse |
| `target_selector` | string | No | CSS selector to extract specific content |
| `remove_selector` | string | No | CSS selector to remove unwanted elements |
| `wait_for_selector` | string | No | CSS selector to wait for before extracting |
| `timeout` | integer | No | Request timeout in milliseconds |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/web/fetch","method":"GET","query":{"url":"<string>","target_selector":"<string>","remove_selector":"<string>","wait_for_selector":"<string>","timeout":"<integer>"}}'
```

### X posts by ID

X Tweets by IDs: Returns normalized X posts by numeric ID. Authentication is required. Each request costs at least 7 credits per unique requested ID; the actual cost reflects plan and tenant pricing. Repeated IDs are billed and looked up once. Unavailable IDs are billed and omitted from `data`; returned posts preserve first-input order.

`GET /gateway/v1/x/tweets`

**Cost:** From $0.04578 per call. Request-based: the price depends on what you send. You see it before you run. You aren't charged for failed calls. A wallet payment for a failed call is refunded.
- $0.04578 per call
- At most $4.578 per call

Use `"dryRun": true` in the Run API request to see a request's price before calling.

**Page:** https://www.orthogonal.com/api/surf/cd49a07b-e1d0-498d-a3f0-791872925586

**Docs:** https://asksurf.ai/

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ids` | string | Yes | Comma-separated numeric tweet IDs, from 1 to 100 values; each ID must contain 1 to 19 digits without leading zeros |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/x/tweets","method":"GET","query":{"ids":"<string>"}}'
```

### Crypto research chat

Research 2.0: OpenAI-compatible Responses API for Surf's conversational crypto research. Non-streaming requests return JSON; streaming requests return Server-Sent Events.

`POST /gateway/v1/responses`

**Cost:** From $0.1308 per call. Request-based: the price depends on what you send. You see it before you run. You aren't charged for failed calls. A wallet payment for a failed call is refunded.
- $0.1308 per call
- At most $1.308 per call

Use `"dryRun": true` in the Run API request to see a request's price before calling.

**Page:** https://www.orthogonal.com/api/surf/fb383774-3aa6-4c39-ae20-6e9af64e9bea

**Docs:** https://docs.asksurf.ai/chat/responses

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | Yes | surf-2.0-instant costs 20 credits per call; surf-2.0 pricing depends on reasoning.effort. |
| `input` | string | Yes | User input for the response. Plain string for simple prompts; advanced callers may send Responses-compatible input item arrays. |
| `instructions` | string | No | Optional system or developer instructions. |
| `stream` | boolean | No | If true, the response is streamed as Server-Sent Events (SSE). |
| `include` | array | No | Optional extra response fields to include when supported by the backend. |
| `max_output_tokens` | integer | No | Maximum number of output tokens to generate. |
| `metadata` | object | No | Optional client metadata. |
| `previous_response_id` | string | No | Previous response ID for continuing a Responses chain. |
| `prompt` | object | No | Optional prompt object for reusable prompt configurations. |
| `reasoning` | object | No | Optional reasoning configuration (OpenAI Responses format); omit for a fast single-pass answer. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"surf","path":"/gateway/v1/responses","body":{"model":"<string>","input":"<string>","instructions":"<string>","stream":"<boolean>","include":"<array>","max_output_tokens":"<integer>","metadata":"<object>","previous_response_id":"<string>","prompt":"<object>","reasoning":"<object>"}}'
```

---

Full details and an interactive quickstart: https://www.orthogonal.com/publisher/surf
