Positions

curl "https://api.metastreams.dev/v1/positions?wallets=7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5&chains=solana&sort=pnl:desc" \
  -H "Authorization: Bearer $API_KEY"

curl "https://api.metastreams.dev/v1/positions?wallets=7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5&lifecycle=closed" \
  -H "Authorization: Bearer $API_KEY"

const url = new URL("https://api.metastreams.dev/v1/positions");
url.searchParams.set("wallets", "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5");
url.searchParams.set("chains", "solana");

const headers = { Authorization: `Bearer ${process.env.API_KEY}` };
let cursor: string | null = null;

do {
  if (cursor) url.searchParams.set("cursor", cursor);
  const response = await fetch(url, { headers });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const page = await response.json();
  for (const position of page.positions) console.log(position.token.symbol, position.value?.usd);
  cursor = page.hasMore ? page.nextCursor : null;
} while (cursor);

{
  "asOf": 123,
  "counts": {
    "spot": {
      "closed": 1,
      "open": 1
    }
  },
  "hasMore": true,
  "positions": [
    {
      "avgCost": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "buyCount": 1,
      "chain": "solana",
      "fees": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "funding": {
        "status": "unresolved",
        "address": "<string>",
        "amount": "123.456789",
        "asset": "<string>",
        "sourceKind": "cex",
        "sourceLabel": "<string>",
        "symbol": "<string>",
        "timestamp": 123,
        "tx": "<string>"
      },
      "holdings": "123.456789",
      "holdingsPctSupply": "123.456789",
      "invested": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "isStablecoin": true,
      "isTransfer": true,
      "lifetime": {
        "buyCount": 1,
        "cycleCount": 1,
        "fees": {
          "native": "123.456789",
          "usd": "123.456789"
        },
        "invested": {
          "native": "123.456789",
          "usd": "123.456789"
        },
        "realizedPnl": {
          "native": "123.456789",
          "usd": "123.456789"
        },
        "received": {
          "native": "123.456789",
          "usd": "123.456789"
        },
        "sellCount": 1,
        "tokensBought": "123.456789",
        "tokensSold": "123.456789",
        "winningCycleCount": 1
      },
      "openedAt": 123,
      "product": "spot",
      "realizedPnl": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "received": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "sellCount": 1,
      "status": "open",
      "token": {
        "address": "<string>",
        "chain": "solana",
        "decimals": 1,
        "image": "<string>",
        "marketCap": {
          "native": "123.456789",
          "usd": "123.456789"
        },
        "name": "<string>",
        "price": {
          "native": "123.456789",
          "usd": "123.456789"
        },
        "symbol": "<string>"
      },
      "tokensBought": "123.456789",
      "tokensSold": "123.456789",
      "updatedAt": 123,
      "version": 123,
      "walletAddress": "<string>",
      "avgEntryMarketCap": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "avgExitMarketCap": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "closedAt": 123,
      "identities": [
        {
          "source": "codex",
          "avatar": "<string>",
          "displayName": "<string>",
          "farcaster": "<string>",
          "handle": "<string>",
          "telegram": "<string>",
          "twitter": "<string>"
        }
      ],
      "pnlPct": "123.456789",
      "totalPnl": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "unrealizedPnl": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "value": {
        "native": "123.456789",
        "usd": "123.456789"
      }
    }
  ],
  "nextCursor": "<string>"
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

GET

positions

curl "https://api.metastreams.dev/v1/positions?wallets=7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5&chains=solana&sort=pnl:desc" \
  -H "Authorization: Bearer $API_KEY"

curl "https://api.metastreams.dev/v1/positions?wallets=7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5&lifecycle=closed" \
  -H "Authorization: Bearer $API_KEY"

const url = new URL("https://api.metastreams.dev/v1/positions");
url.searchParams.set("wallets", "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5");
url.searchParams.set("chains", "solana");

const headers = { Authorization: `Bearer ${process.env.API_KEY}` };
let cursor: string | null = null;

do {
  if (cursor) url.searchParams.set("cursor", cursor);
  const response = await fetch(url, { headers });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const page = await response.json();
  for (const position of page.positions) console.log(position.token.symbol, position.value?.usd);
  cursor = page.hasMore ? page.nextCursor : null;
} while (cursor);

{
  "asOf": 123,
  "counts": {
    "spot": {
      "closed": 1,
      "open": 1
    }
  },
  "hasMore": true,
  "positions": [
    {
      "avgCost": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "buyCount": 1,
      "chain": "solana",
      "fees": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "funding": {
        "status": "unresolved",
        "address": "<string>",
        "amount": "123.456789",
        "asset": "<string>",
        "sourceKind": "cex",
        "sourceLabel": "<string>",
        "symbol": "<string>",
        "timestamp": 123,
        "tx": "<string>"
      },
      "holdings": "123.456789",
      "holdingsPctSupply": "123.456789",
      "invested": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "isStablecoin": true,
      "isTransfer": true,
      "lifetime": {
        "buyCount": 1,
        "cycleCount": 1,
        "fees": {
          "native": "123.456789",
          "usd": "123.456789"
        },
        "invested": {
          "native": "123.456789",
          "usd": "123.456789"
        },
        "realizedPnl": {
          "native": "123.456789",
          "usd": "123.456789"
        },
        "received": {
          "native": "123.456789",
          "usd": "123.456789"
        },
        "sellCount": 1,
        "tokensBought": "123.456789",
        "tokensSold": "123.456789",
        "winningCycleCount": 1
      },
      "openedAt": 123,
      "product": "spot",
      "realizedPnl": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "received": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "sellCount": 1,
      "status": "open",
      "token": {
        "address": "<string>",
        "chain": "solana",
        "decimals": 1,
        "image": "<string>",
        "marketCap": {
          "native": "123.456789",
          "usd": "123.456789"
        },
        "name": "<string>",
        "price": {
          "native": "123.456789",
          "usd": "123.456789"
        },
        "symbol": "<string>"
      },
      "tokensBought": "123.456789",
      "tokensSold": "123.456789",
      "updatedAt": 123,
      "version": 123,
      "walletAddress": "<string>",
      "avgEntryMarketCap": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "avgExitMarketCap": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "closedAt": 123,
      "identities": [
        {
          "source": "codex",
          "avatar": "<string>",
          "displayName": "<string>",
          "farcaster": "<string>",
          "handle": "<string>",
          "telegram": "<string>",
          "twitter": "<string>"
        }
      ],
      "pnlPct": "123.456789",
      "totalPnl": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "unrealizedPnl": {
        "native": "123.456789",
        "usd": "123.456789"
      },
      "value": {
        "native": "123.456789",
        "usd": "123.456789"
      }
    }
  ],
  "nextCursor": "<string>"
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

The spot positions of the wallets you name, one row per chain, wallet and token. wallets takes 1 to 100 addresses, comma-separated. chains narrows the read to some chains.

Filters

lifecycle picks open positions, the default, or closed ones.
hideLowLiquidity drops open positions in tokens with under $1,000 of liquidity. It is true by default. Send false to see every position.
hideDust drops open positions worth under $1. It is false by default.
hideTransfers drops positions that no buy opened, such as airdrops. It is false by default.
chain and token together read one token’s positions. Send both or neither.
q keeps tokens whose symbol or name contains it, in any letter case.

Sort

sort is field:asc or field:desc, where field is value, pnl, pnlPct, openedAt or closedAt. It is value:desc for open positions and closedAt:desc for closed ones.

Response

A page carries positions, nextCursor, hasMore, asOf and counts. counts.spot holds the number of open and closed positions. It ignores lifecycle, the hide… switches, q, chain and token, so it stays the same across the pages of one read. Each position prices its holdings at the token’s latest price. value, unrealizedPnl, totalPnl and pnlPct are null for a token with no market record, and pnlPct is also null for a position with no invested cost. version orders the changes to one position: keep the highest. The spot.positions stream uses the same rule.

Paging

Send back nextCursor exactly as you received it. A cursor holds the filters and sort of the read that made it. A cursor sent with other filters is refused with 400 VALIDATION_ERROR.

Errors

Code	When
`UNSUPPORTED_CHAIN`	A `chains` or `chain` value is not a supported slug
`VALIDATION_ERROR`	No wallet or more than 100; a malformed wallet or token address; `chain` without `token`, or the reverse; an unknown sort; a cursor from other filters; or an unknown parameter

curl "https://api.metastreams.dev/v1/positions?wallets=7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5&chains=solana&sort=pnl:desc" \
  -H "Authorization: Bearer $API_KEY"

curl "https://api.metastreams.dev/v1/positions?wallets=7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5&lifecycle=closed" \
  -H "Authorization: Bearer $API_KEY"

const url = new URL("https://api.metastreams.dev/v1/positions");
url.searchParams.set("wallets", "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5");
url.searchParams.set("chains", "solana");

const headers = { Authorization: `Bearer ${process.env.API_KEY}` };
let cursor: string | null = null;

do {
  if (cursor) url.searchParams.set("cursor", cursor);
  const response = await fetch(url, { headers });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const page = await response.json();
  for (const position of page.positions) console.log(position.token.symbol, position.value?.usd);
  cursor = page.hasMore ? page.nextCursor : null;
} while (cursor);

Authorizations

Authorization

string

header

required

Send the API key as Authorization: Bearer <key>.

Query Parameters

wallets

string

required

Wallet addresses, CSV; one to 100.

chains

string

Chains to scope to, CSV of the chain slugs. Absent means every spot chain.

lifecycle

enum<string>

Lifecycle to list; open when absent. A position's current-cycle lifecycle.

Available options:

open,

closed

hideLowLiquidity

boolean

default:true

Drop open positions whose token liquidity is below the low-liquidity floor.

hideDust

boolean

Drop open positions whose remaining value is below the dust floor.

hideTransfers

boolean

Drop positions never acquired through a buy.

chain

string

Exact-token drill-down chain; requires token.

token

string

Exact-token drill-down address; requires chain.

string

Case-insensitive substring of the token symbol or name.

sort

string

Sort field and direction, field:asc|desc. value:desc when absent, closedAt:desc for closed.

limit

integer<int32>

Rows per page, clamped to 1-100; 50 when absent.

Required range: 1 <= x <= 100

cursor

string

Opaque cursor from the previous page.

Response

One page of the named wallets' positions. The price-derived fields are null for a token without a price.

One page of the named wallets' positions.

asOf

integer<int64>

required

Serve-time snapshot timestamp.

counts

object

required

Per-product counts, taken before the lifecycle, display, search and drill-down filters.

Show child attributes

hasMore

boolean

required

Whether a next page exists.

positions

object[]

required

Positions on this page.

Show child attributes

nextCursor

string | null

Cursor for the next page; null on the last page.

REST

Streams

Filters

Sort

Response

Paging

Errors

Authorizations

Query Parameters

Response

​Filters

​Sort

​Response

​Paging

​Errors

Authorizations

Query Parameters

Response

Filters

Sort

Response

Paging

Errors