For agents
Give your agent a window on every stock-token book.
01 · MCP
Mount the MCP server
Client config
{
"mcpServers": {
"stocksat": {
"url": "https://stocksat.xyz/mcp",
"headers": { "Authorization": "Bearer ss_live_…" }
}
}
}Stateless Streamable HTTP with plain JSON answers. Without a key you get 100 tool calls a day per IP. With a key, your plan's quota applies.
Tools
list_marketsAll stock tokens with price, change, volume, OI and funding.get_quoteSpot + perp price, mark, index, OI for one token.get_bookOrder book by price with spread and USD depth.get_derivsFunding across venues, OI, premium, 24h funding.get_whalesLarge fills, newest first.get_candlesOHLC with USD volume, 15m to 1d.signal_reportThe latest hourly SIGNAL REPORT.
02 · REST
Endpoints and prices
Every response has the same shape: { data, downlink }. downlink is your receipt: id, channel, charge, latency and, when paid, the transaction.
| Endpoint | Satellite | Price per call |
|---|---|---|
| GET /api/v1/quote/{symbol} | Pip | 0.001 USDG |
| GET /api/v1/book/{symbol} | Lumen | 0.002 USDG |
| GET /api/v1/derivs/{symbol} | Tide | 0.001 USDG |
| GET /api/v1/whales | Sentry | 0.003 USDG |
| GET /api/v1/candles/{symbol} | Pip | 0.002 USDG |
| GET /api/v1/markets · /reports · /status | — | Free |
| Endpoint | Parameters | Returns |
|---|---|---|
| /api/v1/quote/{symbol} | — | Spot and perp price, 24h change, high, low, volume, mark, index and open interest for one Robinhood Chain stock token. |
| /api/v1/book/{symbol} | venue=spot|perp, depth=1..50 | Live order book (spot or perp) aggregated by price, with spread and USD depth within 10/50/100 bps. |
| /api/v1/derivs/{symbol} | — | Perp mark, index, premium, open interest and funding (Lighter plus other venues) with the last 24 hours of funding. |
| /api/v1/whales | symbol?, min_usd≥5000, hours≤168 | Large single fills on Robinhood Chain stock-token books over the last hours, newest first. |
| /api/v1/candles/{symbol} | venue, resolution=15m|1h|4h|1d, limit≤500 | OHLC candles with USD volume (15m, 1h, 4h, 1d) for spot or perp. |
With an API key
curl https://stocksat.xyz/api/v1/quote/TSLA \ -H "Authorization: Bearer ss_live_…"
03 · x402
Pay per call, no account
Call without credentials and you get 402 Payment Required. Sign a USDG transfer authorization for that exact amount, send it back, and the data comes with a receipt.
402 + PAYMENT-REQUIRED
Base64 JSON with x402Version 2 and accepts[0]: scheme exact, network eip155:4663, amount in USDG base units (6 decimals), asset, payTo, maxTimeoutSeconds 300, extra { name: "Global Dollar", version: "1" }. The body repeats it in x402 v1 form (network "robinhood").
PAYMENT-SIGNATURE
Base64 JSON { x402Version: 2, accepted, payload: { signature, authorization } }. v1 clients can send X-PAYMENT instead. The authorization is ERC-3009 transferWithAuthorization on USDG: from, to, value, validAfter, validBefore, nonce.
200 + PAYMENT-RESPONSE
Base64 JSON { success, transaction, network, payer }, also in X-PAYMENT-RESPONSE. We check the request and fetch the data before we settle, so a failed call is never charged, and each authorization works once.
TypeScript · viem
import { toHex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
const account = privateKeyToAccount(process.env.AGENT_KEY as `0x${string}`);
const url = "https://stocksat.xyz/api/v1/book/NVDA?venue=spot&depth=20";
// 1. Ask. The answer is 402 with the exact price.
const first = await fetch(url);
const challenge = JSON.parse(atob(first.headers.get("PAYMENT-REQUIRED")!));
const req = challenge.accepts[0]; // scheme "exact", network "eip155:4663", asset USDG
// 2. Sign a USDG transfer authorization (ERC-3009). No gas.
const now = Math.floor(Date.now() / 1000);
const authorization = {
from: account.address, to: req.payTo, value: req.amount,
validAfter: String(now - 60), validBefore: String(now + 300),
nonce: toHex(crypto.getRandomValues(new Uint8Array(32))),
};
const signature = await account.signTypedData({
domain: { name: "Global Dollar", version: "1", chainId: 4663, verifyingContract: req.asset },
types: { TransferWithAuthorization: [
{ name: "from", type: "address" }, { name: "to", type: "address" },
{ name: "value", type: "uint256" }, { name: "validAfter", type: "uint256" },
{ name: "validBefore", type: "uint256" }, { name: "nonce", type: "bytes32" } ] },
primaryType: "TransferWithAuthorization",
message: { ...authorization, value: BigInt(authorization.value),
validAfter: BigInt(authorization.validAfter), validBefore: BigInt(authorization.validBefore) },
});
// 3. Send it back. Data plus an on-chain receipt.
const paid = await fetch(url, { headers: { "PAYMENT-SIGNATURE": btoa(JSON.stringify({
x402Version: 2, resource: challenge.resource, accepted: req, payload: { signature, authorization },
})) } });
const { data, downlink } = await paid.json();
console.log(data.mid, downlink.tx); // tx on Robinhood ChainPython · eth-account
import base64, json, os, secrets, time, requests
from eth_account import Account
from eth_account.messages import encode_typed_data
acct = Account.from_key(os.environ["AGENT_KEY"])
url = "https://stocksat.xyz/api/v1/derivs/SPY"
r = requests.get(url) # 402
ch = json.loads(base64.b64decode(r.headers["PAYMENT-REQUIRED"]))
req = ch["accepts"][0]
now = int(time.time())
auth = {"from": acct.address, "to": req["payTo"], "value": int(req["amount"]),
"validAfter": now - 60, "validBefore": now + 300, "nonce": "0x" + secrets.token_hex(32)}
msg = encode_typed_data(full_message={
"types": {"EIP712Domain": [{"name": "name", "type": "string"}, {"name": "version", "type": "string"},
{"name": "chainId", "type": "uint256"}, {"name": "verifyingContract", "type": "address"}],
"TransferWithAuthorization": [{"name": "from", "type": "address"}, {"name": "to", "type": "address"},
{"name": "value", "type": "uint256"}, {"name": "validAfter", "type": "uint256"},
{"name": "validBefore", "type": "uint256"}, {"name": "nonce", "type": "bytes32"}]},
"domain": {"name": "Global Dollar", "version": "1", "chainId": 4663, "verifyingContract": req["asset"]},
"primaryType": "TransferWithAuthorization", "message": auth})
sig = acct.sign_message(msg).signature.hex()
payload = {"x402Version": 2, "resource": ch["resource"], "accepted": req,
"payload": {"signature": "0x" + sig.removeprefix("0x"),
"authorization": {k: str(v) for k, v in auth.items()}}}
paid = requests.get(url, headers={"PAYMENT-SIGNATURE": base64.b64encode(json.dumps(payload).encode()).decode()})
print(paid.json()["downlink"]["tx"])Discovery
Catalogues and agents can list every paid resource, with price and example input, at https://stocksat.xyz/api/x402/discovery/resources.
04 · Errors
Status codes
| 200 | Data plus downlink receipt. |
| 401 | No key and pay-per-call not open, or an unknown key. |
| 402 | Payment required, or the payment was refused. The PAYMENT-REQUIRED header says why in error. |
| 404 | Unknown symbol, or no perp market for that token. |
| 429 | Rate limit or daily quota. Retry-After says when. |
| 502 | The upstream book did not answer. charged: false. |
| 503 | Maintenance window. |