Positions

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

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

const url = new URL("https://api.metastreams.io/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);

use serde_json::Value;

let key = std::env::var("API_KEY")?;
let client = reqwest::Client::new();
let mut cursor: Option<String> = None;

loop {
    let mut request = client
        .get("https://api.metastreams.io/v1/positions")
        .query(&[("wallets", "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5"), ("chains", "solana")])
        .bearer_auth(&key);
    if let Some(cursor) = &cursor {
        request = request.query(&[("cursor", cursor)]);
    }
    let page: Value = request.send().await?.error_for_status()?.json().await?;
    for position in page["positions"].as_array().into_iter().flatten() {
        println!("{} {}", position["token"]["symbol"].as_str().unwrap_or_default(), position["value"]["usd"].as_str().unwrap_or("null"));
    }
    if page["hasMore"] != true {
        break;
    }
    cursor = page["nextCursor"].as_str().map(String::from);
}

{
  "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,
        "logoUrl": "<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.io/v1/positions?wallets=7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5&chains=solana&sort=pnl:desc" \
  -H "Authorization: Bearer $API_KEY"

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

const url = new URL("https://api.metastreams.io/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);

use serde_json::Value;

let key = std::env::var("API_KEY")?;
let client = reqwest::Client::new();
let mut cursor: Option<String> = None;

loop {
    let mut request = client
        .get("https://api.metastreams.io/v1/positions")
        .query(&[("wallets", "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5"), ("chains", "solana")])
        .bearer_auth(&key);
    if let Some(cursor) = &cursor {
        request = request.query(&[("cursor", cursor)]);
    }
    let page: Value = request.send().await?.error_for_status()?.json().await?;
    for position in page["positions"].as_array().into_iter().flatten() {
        println!("{} {}", position["token"]["symbol"].as_str().unwrap_or_default(), position["value"]["usd"].as_str().unwrap_or("null"));
    }
    if page["hasMore"] != true {
        break;
    }
    cursor = page["nextCursor"].as_str().map(String::from);
}

{
  "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,
        "logoUrl": "<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>"
  }
}

Returns the spot positions of the requested wallets, with one row per chain, wallet and token. wallets takes 1 to 100 comma-separated addresses, and chains limits results to specific chains.

Filters

lifecycle selects open positions (the default) or closed positions.
hideLowLiquidity excludes open positions in tokens with under $1,000 of liquidity. The default is true; send false to include every position.
hideDust excludes open positions worth under $1. The default is false.
hideTransfers excludes positions not opened by a buy, such as airdrops. The default is false.
chain and token together limit results to one token’s positions and must be sent together.
q matches tokens whose symbol or name contains the value, case-insensitively.

Sort

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

Response

A page contains positions, nextCursor, hasMore, asOf and counts. counts.spot is the number of open and closed positions. It ignores lifecycle, the hide… parameters, q, chain and token, so it stays the same across all pages of one request. Holdings are valued 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 a position, and the highest version is the current one. The spot.positions stream follows the same rule.

Pagination

Send nextCursor back exactly as received. A cursor encodes the filters and sort of the request that produced it, so a cursor sent with different filters returns 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.io/v1/positions?wallets=7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5&chains=solana&sort=pnl:desc" \
  -H "Authorization: Bearer $API_KEY"

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

const url = new URL("https://api.metastreams.io/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);

use serde_json::Value;

let key = std::env::var("API_KEY")?;
let client = reqwest::Client::new();
let mut cursor: Option<String> = None;

loop {
    let mut request = client
        .get("https://api.metastreams.io/v1/positions")
        .query(&[("wallets", "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5"), ("chains", "solana")])
        .bearer_auth(&key);
    if let Some(cursor) = &cursor {
        request = request.query(&[("cursor", cursor)]);
    }
    let page: Value = request.send().await?.error_for_status()?.json().await?;
    for position in page["positions"].as_array().into_iter().flatten() {
        println!("{} {}", position["token"]["symbol"].as_str().unwrap_or_default(), position["value"]["usd"].as_str().unwrap_or("null"));
    }
    if page["hasMore"] != true {
        break;
    }
    cursor = page["nextCursor"].as_str().map(String::from);
}

Authorizations

Authorization

string

header

required

Send an API key, or a session token a key minted, as Authorization: Bearer <credential>. A browser opening /v1/stream offers its session token in Sec-WebSocket-Protocol instead.

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

Errors

Authorizations

Query Parameters

Response

​Filters

​Sort

​Response

​Pagination

​Errors

Authorizations

Query Parameters

Response

Filters

Sort

Response

Pagination

Errors