Quickstart

This guide reads one Solana token, fetches its candles, and streams its trades live. It uses BONK (DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263) as the example token.

Set your API key

If you have no key yet, see Get an API key. Then export it in your shell:

export API_KEY="chr_..."

Read a token

Request the token object. Every request sends the key as a bearer token.

curl "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" \
  -H "Authorization: Bearer $API_KEY"

import os
import requests

response = requests.get(
    "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    timeout=10,
)
response.raise_for_status()
token = response.json()
print(token["symbol"], token["price"]["usd"])

const response = await fetch(
  "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  { headers: { Authorization: `Bearer ${process.env.API_KEY}` } },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const token = await response.json();
console.log(token.symbol, token.price.usd);

The response is the token object. This one is shortened:

{
  "chain": "solana",
  "address": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "name": "Bonk",
  "symbol": "Bonk",
  "decimals": 5,
  "price": { "native": "0.000000121", "usd": "0.0000216" },
  "marketCap": { "native": "10741962.1", "usd": "1917440000" },
  "liquidity": { "native": "61230.4", "usd": "10929626" },
  "stats": {
    "24h": {
      "priceChangePct": "-3.4",
      "volume": { "native": "301422.8", "usd": "53803970" },
      "buyCount": 48211,
      "sellCount": 45390,
      "buyVolume": { "native": "151002.1", "usd": "26953870" },
      "sellVolume": { "native": "150420.7", "usd": "26850100" }
    }
  },
  "holders": { "count": 972311, "top10Pct": "31.7", "sniperPct": "0.2" },
  "security": { "mintDisabled": true, "transferBlockable": false },
  "updatedAt": 1789632012345
}

Prices and amounts are decimal strings, and every priced value carries both a native and a usd value. Reading responses explains each convention.

Fetch candles

Request the last 24 hourly candles, priced in USD:

curl "https://api.metastreams.io/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/ohlcv?timeframe=1h&metric=price&countBack=24" \
  -H "Authorization: Bearer $API_KEY"

{
  "candles": [
    { "time": 1789545600000, "open": 0.0000221, "high": 0.0000224, "low": 0.0000219, "close": 0.0000222, "volume": 2104410.5 },
    { "time": 1789549200000, "open": 0.0000222, "high": 0.0000223, "low": 0.0000215, "close": 0.0000216, "volume": 2981337.2 }
  ]
}

Candles come oldest first, and time is the bucket’s open time in milliseconds. A bucket with no trades is left out.

Stream live trades

Install wscat, then connect with your key on the handshake:

npm install -g wscat
wscat -c "wss://api.metastreams.io/v1/stream" -H "Authorization: Bearer $API_KEY"

Once connected, send a subscribe frame:

{"action": "subscribe", "channel": "spot.trades", "filters": {"chain": "solana", "token": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"}, "id": "bonk-trades"}

The server confirms the subscription:

{"type": "ack", "channel": "spot.trades", "subscriptionId": "5f0c6d1e-8a2b-4c3d-9e4f-1a2b3c4d5e6f", "id": "bonk-trades", "status": "success", "message": "subscribe successful"}

Then it sends one update frame per trade:

{"type": "update", "channel": "spot.trades", "subscriptionId": "5f0c6d1e-8a2b-4c3d-9e4f-1a2b3c4d5e6f", "data": {"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"}, "timestamp": 1789632015120}}

Each update’s data is the trade object the REST trades endpoint returns. A subscription by token leaves out flags and platforms; see spot.trades.

Next steps

Reading responses

Prices, decimals, percentages and timestamps.

Connecting to streams

Every frame, every channel, and how to reconnect.

Errors, limits and retries

Handle every error code correctly, and stay inside the limits.

Token trades

Page through a token’s full trade history.

Get started

Core concepts

Streams

Recipes

Migration guides

Resources

Next steps

Reading responses

Connecting to streams

Errors, limits and retries

Token trades

​Next steps

Reading responses

Connecting to streams

Errors, limits and retries

Token trades

Next steps