> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metastreams.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Identity trades
> Page through trades by notable wallets across every chain and token.
Recent trades by one identity feed, newest first, across every token. This is the only trade read not scoped to a token.
`identity` picks the feed. `kol` covers wallets labelled as key opinion leaders, and `fomoscan` covers wallets with a fomo.family profile. `chains` scopes the read to a comma-separated list of [chain slugs](/concepts/chains), such as `solana,base`; leave it out for every spot chain, because a list that names nothing is refused.
## Response
The page shape of [Token trades](/reference/rest/token-trades#response): `trades`, `nextCursor` and `hasMore`. Each trade names its own `chain` and `token`, because one page spans both. The cursor behaves the same way here; see [Paging](/reference/rest/token-trades#paging).
## Errors
| Code | When |
| - | - |
| `UNSUPPORTED_CHAIN` | A slug in `chains` is not supported |
| `VALIDATION_ERROR` | An unknown `identity`, an empty `chains` list, a cursor that does not decode, or an unknown parameter |
```bash cURL theme={null}
curl "https://api.metastreams.io/v1/trades?identity=kol&limit=50" \
-H "Authorization: Bearer $API_KEY"
```
```bash Scoped theme={null}
curl "https://api.metastreams.io/v1/trades?identity=fomoscan&chains=solana,base" \
-H "Authorization: Bearer $API_KEY"
```
```typescript TypeScript theme={null}
const url = new URL("https://api.metastreams.io/v1/trades");
url.searchParams.set("identity", "kol");
url.searchParams.set("chains", "solana,base");
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { trades, nextCursor, hasMore } = await response.json();
```
```json Page theme={null}
{
"trades": [
{
"id": "4xQmVb8e2kT1nR7pZcW3sLdHfA9jEuY6gVnX1oB5iC0wQ2rT8yU3iO7pA1sD4fG6h:2",
"chain": "solana",
"token": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
"name": "Bonk",
"symbol": "Bonk",
"trader": "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5",
"transactionHash": "4xQmVb8e2kT1nR7pZcW3sLdHfA9jEuY6gVnX1oB5iC0wQ2rT8yU3iO7pA1sD4fG6h",
"side": "buy",
"amount": "12500000",
"price": { "native": "0.000000121", "usd": "0.0000216" },
"volume": { "native": "1.51", "usd": "270.12" },
"marketCap": { "native": "10741962.1", "usd": "1917440000" },
"identities": [
{
"source": "fomoscan",
"handle": "degenspartan",
"displayName": "Degen Spartan",
"avatar": "https://cdn.example.com/avatars/degenspartan.png",
"twitter": "degenspartan",
"telegram": null,
"farcaster": null
}
],
"timestamp": 1789632015120
}
],
"nextCursor": null,
"hasMore": false
}
```
```json Unknown feed theme={null}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "One or more parameters are invalid.",
"details": [{ "field": "identity", "message": "Must be one of: kol, fomoscan." }]
}
}
```
## OpenAPI
````yaml specs/openapi.json GET /v1/trades
openapi: 3.1.0
info:
title: Metastreams API
description: >-
Click's B2B market-data API. Amounts are decimal strings, timestamps are
Unix milliseconds, and every field name is camelCase.
license:
name: Proprietary
identifier: Proprietary
version: 1.0.0
servers:
- url: https://{host}
variables:
host:
default: api.metastreams.io
description: API host.
security:
- bearerKey: []
paths:
/v1/trades:
get:
tags:
- trades
summary: Recent trades by a notable identity, across every chain and token.
description: |-
`identity` names the feed: `kol` for curated wallets, `fomoscan` for
wallets resolved to a fomo.family identity. `chains` narrows the scope,
and every spot chain is read when it is absent. Page with `cursor` until
`hasMore` is false.
operationId: identity_trades
parameters:
- name: identity
in: query
description: Which identity feed to read.
required: true
schema:
$ref: '#/components/schemas/IdentityFeed'
- name: chains
in: query
description: >-
Chains to scope to, CSV of the chain slugs. Absent means every spot
chain.
required: false
schema:
type: string
example: solana,base
- name: limit
in: query
description: Rows per page, clamped to 1-100; 20 when absent.
required: false
schema:
type: integer
format: int32
maximum: 100
minimum: 1
- name: cursor
in: query
description: Opaque cursor from the previous page.
required: false
schema:
type: string
responses:
'200':
description: Recent trades by the requested identity, newest first.
headers:
X-Credits-Cost:
schema:
type: integer
description: >-
Credits charged for this request. Zero on any non-2xx. Sent on a
metered tier only.
X-Credits-Remaining:
schema:
type: integer
description: Credit balance after this request. Sent on a metered tier only.
X-RateLimit-Remaining:
schema:
type: integer
description: Requests left in the current rate-limit window.
X-Request-ID:
schema:
type: string
description: >-
This request's trace ID. Echoed from the request, or generated
when it sent none.
content:
application/json:
schema:
$ref: '#/components/schemas/UiSpotTrades'
'400':
description: >-
Unknown identity feed, unsupported chain, a bad cursor, or a
malformed parameter.
headers:
X-Credits-Cost:
schema:
type: integer
description: >-
Credits charged for this request. Zero on any non-2xx. Sent on a
metered tier only.
X-Credits-Remaining:
schema:
type: integer
description: Credit balance after this request. Sent on a metered tier only.
X-RateLimit-Remaining:
schema:
type: integer
description: Requests left in the current rate-limit window.
X-Request-ID:
schema:
type: string
description: >-
This request's trace ID. Echoed from the request, or generated
when it sent none.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Missing or invalid API key.
headers:
X-Credits-Cost:
schema:
type: integer
description: >-
Credits charged for this request. Zero on any non-2xx. Sent on a
metered tier only.
X-Credits-Remaining:
schema:
type: integer
description: Credit balance after this request. Sent on a metered tier only.
X-RateLimit-Remaining:
schema:
type: integer
description: Requests left in the current rate-limit window.
X-Request-ID:
schema:
type: string
description: >-
This request's trace ID. Echoed from the request, or generated
when it sent none.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Rate limit exceeded.
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying.
X-Credits-Cost:
schema:
type: integer
description: >-
Credits charged for this request. Zero on any non-2xx. Sent on a
metered tier only.
X-Credits-Remaining:
schema:
type: integer
description: Credit balance after this request. Sent on a metered tier only.
X-RateLimit-Remaining:
schema:
type: integer
description: Requests left in the current rate-limit window.
X-Request-ID:
schema:
type: string
description: >-
This request's trace ID. Echoed from the request, or generated
when it sent none.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Unexpected server failure.
headers:
X-Credits-Cost:
schema:
type: integer
description: >-
Credits charged for this request. Zero on any non-2xx. Sent on a
metered tier only.
X-Credits-Remaining:
schema:
type: integer
description: Credit balance after this request. Sent on a metered tier only.
X-RateLimit-Remaining:
schema:
type: integer
description: Requests left in the current rate-limit window.
X-Request-ID:
schema:
type: string
description: >-
This request's trace ID. Echoed from the request, or generated
when it sent none.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Dependency down or maintenance.
headers:
X-Credits-Cost:
schema:
type: integer
description: >-
Credits charged for this request. Zero on any non-2xx. Sent on a
metered tier only.
X-Credits-Remaining:
schema:
type: integer
description: Credit balance after this request. Sent on a metered tier only.
X-RateLimit-Remaining:
schema:
type: integer
description: Requests left in the current rate-limit window.
X-Request-ID:
schema:
type: string
description: >-
This request's trace ID. Echoed from the request, or generated
when it sent none.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
components:
schemas:
IdentityFeed:
type: string
description: >-
A cross-token feed of trades by a notable identity: `GET
/v1/trades?identity=`.
enum:
- kol
- fomoscan
UiSpotTrades:
type: object
description: >-
A page of trades, newest first: one token's (`GET
/v1/tokens/{chain}/{address}/trades`)
or one identity's across every token (`GET /v1/trades`).
required:
- trades
- hasMore
properties:
hasMore:
type: boolean
description: Whether a next page exists.
nextCursor:
type:
- string
- 'null'
description: Cursor for the next page; `null` on the last page.
trades:
type: array
items:
$ref: '#/components/schemas/UiSpotTrade'
description: Trades on the requested page, newest first.
ErrorEnvelope:
type: object
description: The complete error response body — every error is exactly this.
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
description: The error.
UiSpotTrade:
type: object
description: One executed swap on the token.
required:
- id
- chain
- token
- name
- symbol
- trader
- transactionHash
- side
- amount
- price
- volume
- marketCap
- timestamp
properties:
amount:
$ref: '#/components/schemas/Decimal'
description: Token units traded.
chain:
$ref: '#/components/schemas/SpotChain'
description: Chain the trade executed on.
flags:
type: array
items:
type: string
description: >-
A flag the classifier put on the wallet. This is an open
enumeration: the classifier learns new flags, so keep a value you
do not recognize.
examples:
- bundler
- sniper
- insider
- dev
- fresh
- whale
- kol
- liquidity_pool
- locker
- pro_trader
- system
- fomo
- phishing
description: Classifications the trader wallet carries.
id:
type: string
description: >-
Stable identity for this trade, opaque to the caller. One
transaction can settle several
trades on a token, so this is not a transaction hash — never parse
it.
identities:
type: array
items:
$ref: '#/components/schemas/UiWalletIdentity'
description: Trader's resolved identities, one element per source.
marketCap:
$ref: '#/components/schemas/UiMoney'
description: Token market cap at execution.
name:
type: string
description: Traded token's name; empty until the token's metadata resolves.
platforms:
type: array
items:
$ref: '#/components/schemas/UiPlatform'
description: >-
Terminals this trade routed through. A trader's profile is an
element of
`identities`.
price:
$ref: '#/components/schemas/UiMoney'
description: Token price at execution.
side:
$ref: '#/components/schemas/TradeDirection'
description: Buy or sell.
symbol:
type: string
description: Traded token's symbol; empty until the token's metadata resolves.
timestamp:
$ref: '#/components/schemas/UnixMilliseconds'
description: When the trade executed.
token:
type: string
description: Traded token's address.
trader:
type: string
description: Wallet that sent the swap.
transactionHash:
type: string
description: On-chain transaction hash.
volume:
$ref: '#/components/schemas/UiMoney'
description: Trade value.
ErrorDetail:
type: object
description: The `error` object inside the envelope.
required:
- code
- message
properties:
code:
$ref: '#/components/schemas/ErrorCode'
description: >-
Stable, machine-readable. Clients switch on this, never on
`message`.
details:
description: Optional; shape is fixed per code.
message:
type: string
description: |-
Human-readable, written for the integrating developer:
`[What happened]. [What to do next — if actionable].`
Decimal:
type: string
format: decimal
description: An exact decimal, as a string.
example: '123.456789'
SpotChain:
type: string
description: >-
Chain slug. One spelling per chain, in paths and bodies alike. Only a
chain with spot data is published.
enum:
- solana
- base
- bsc
- robinhood
- arc
UiWalletIdentity:
type: object
description: One source's resolved profile for a trade's trader.
required:
- source
properties:
avatar:
type:
- string
- 'null'
description: >-
CDN URL of the avatar to render; `null` until the picture is
mirrored.
displayName:
type:
- string
- 'null'
description: Human-readable name to render.
farcaster:
type:
- string
- 'null'
description: The wallet's Farcaster handle, where the source links one.
handle:
type:
- string
- 'null'
description: The wallet's handle on the source.
source:
$ref: '#/components/schemas/IdentitySource'
description: Who resolved this identity.
telegram:
type:
- string
- 'null'
description: The wallet's Telegram handle, where the source links one.
twitter:
type:
- string
- 'null'
description: The wallet's bare X handle, where the source links one.
UiMoney:
type: object
description: >-
A chain-denominated value with its USD equivalent. The enclosing object
carries the
`chain` that names `native`'s unit.
required:
- native
properties:
native:
$ref: '#/components/schemas/Decimal'
description: Value in the owning chain's gas asset.
usd:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/Decimal'
description: Value in USD; `null` when the native asset is unpriced.
description: Value in USD; `null` when the native asset is unpriced.
UiPlatform:
oneOf:
- type: object
description: >-
fomo.family, the terminal that routed the trade. The trader's
profile is the `fomoscan`
element of `identities`.
required:
- platform
properties:
platform:
type: string
enum:
- fomo
- type: object
description: >-
A token's DexScreener listing; present only while its profile is
paid.
required:
- isPaid
- platform
properties:
isPaid:
type: boolean
description: Whether the token's DexScreener profile is paid.
paidAt:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/UnixMilliseconds'
description: Earliest profile payment time.
platform:
type: string
enum:
- dexScreener
- type: object
description: Axiom.
required:
- platform
properties:
platform:
type: string
enum:
- axiom
- type: object
description: '"Banana Gun".'
required:
- platform
properties:
platform:
type: string
enum:
- bananaGun
- type: object
description: Bloom.
required:
- platform
properties:
platform:
type: string
enum:
- bloom
- type: object
description: '"BONKbot".'
required:
- platform
properties:
platform:
type: string
enum:
- bonkbot
- type: object
description: BtcTurk.
required:
- platform
properties:
platform:
type: string
enum:
- btcTurk
- type: object
description: BullX.
required:
- platform
properties:
platform:
type: string
enum:
- bullX
- type: object
description: Click's own router, identified by its fee vault.
required:
- platform
properties:
platform:
type: string
enum:
- click
- type: object
description: '"GMGN".'
required:
- platform
properties:
platform:
type: string
enum:
- gmgn
- type: object
description: '"Lucky Block".'
required:
- platform
properties:
platform:
type: string
enum:
- luckyBlock
- type: object
description: Maestro.
required:
- platform
properties:
platform:
type: string
enum:
- maestro
- type: object
description: '"Manifold Trading".'
required:
- platform
properties:
platform:
type: string
enum:
- manifoldTrading
- type: object
description: '"MEVX".'
required:
- platform
properties:
platform:
type: string
enum:
- mevx
- type: object
description: Mintech.
required:
- platform
properties:
platform:
type: string
enum:
- mintech
- type: object
description: Nighthawk.
required:
- platform
properties:
platform:
type: string
enum:
- nighthawk
- type: object
description: Nova.
required:
- platform
properties:
platform:
type: string
enum:
- nova
- type: object
description: '"OX.FUN".'
required:
- platform
properties:
platform:
type: string
enum:
- oxFun
- type: object
description: Padre.
required:
- platform
properties:
platform:
type: string
enum:
- padre
- type: object
description: PepeBoost.
required:
- platform
properties:
platform:
type: string
enum:
- pepeBoost
- type: object
description: Phantom.
required:
- platform
properties:
platform:
type: string
enum:
- phantom
- type: object
description: Photon.
required:
- platform
properties:
platform:
type: string
enum:
- photon
- type: object
description: SexBotSolana.
required:
- platform
properties:
platform:
type: string
enum:
- sexBotSolana
- type: object
description: Shuriken.
required:
- platform
properties:
platform:
type: string
enum:
- shuriken
- type: object
description: '"SOL Sniper Bot".'
required:
- platform
properties:
platform:
type: string
enum:
- solSniperBot
- type: object
description: '"Sol Trading Bot".'
required:
- platform
properties:
platform:
type: string
enum:
- solTradingBot
- type: object
description: Trojan.
required:
- platform
properties:
platform:
type: string
enum:
- trojan
description: >-
A platform attached to a token, a wallet, or a trade.
The fieldless variants are trading terminals. Each doc gives the
producer string its
variant maps from.
TradeDirection:
type: string
description: 'Which way the traded token moved: `buy` or `sell`.'
enum:
- buy
- sell
UnixMilliseconds:
type: integer
format: int64
description: An instant, as milliseconds since the Unix epoch.
ErrorCode:
type: string
description: |-
Every wire error code the API can return.
Append-only: a new code is non-breaking, since clients fall back on the
HTTP status for one they do not recognize, and a published code is never
renamed or removed.
enum:
- UNAUTHORIZED
- FORBIDDEN
- VALIDATION_ERROR
- UNSUPPORTED_CHAIN
- NOT_FOUND
- RATE_LIMITED
- CREDITS_EXHAUSTED
- INTERNAL_ERROR
- SERVICE_UNAVAILABLE
IdentitySource:
type: string
description: >-
Who resolved a trader's identity. The set grows; keep a value you do not
recognize.
enum:
- codex
- fomoscan
- unknown
securitySchemes:
bearerKey:
type: http
scheme: bearer
description: 'Send the API key as `Authorization: Bearer `.'
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.