API

GET/v1/token/{mint}

One verdict for one mint.

curl -s "$BSOAD/v1/token/EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm"

# with a key: a fresh check, no cache
curl -s -H "x-api-key: $BSOAD_KEY" "$BSOAD/v1/token/EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm?fresh=1"

const v = await bsoad<Verdict>(`/v1/token/${mint}`);
if (v.verdict === 'stop') {
  showBlueScreen(v.stopCode, v.reasons.map((r) => r.text));
}
if (v.skipped.includes('sell-sim')) {
  // the sell was not simulated: say so, do not call it safe
}

200, a real reply

{
  "mint": "EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm",
  "verdict": "ok",
  "code": "CLEAN",
  "stopCode": "STOP: 0x0000B50AD CLEAN",
  "reasons": [],
  "skipped": ["holders", "sell-sim"],
  "meta": {
    "program": "spl-token", "decimals": 6, "supply": "998836642292950",
    "mintAuthority": null, "freezeAuthority": null, "known": false,
    "symbol": "$WIF", "name": "dogwifhat", "image": "https://cdn.dexscreener.com/…",
    "priceUsd": 0.1708, "liquidityUsd": 5216990,
    "dex": ["raydium", "orca", "meteora", "fluxbeam"]
  },
  "checkedAt": "2026-11-03T11:27:56.045Z"
}

A stop reason looks like this

"verdict": "stop",
"code": "FREEZE_AUTHORITY_ACTIVE",
"stopCode": "STOP: 0x0000B50AD FREEZE_AUTHORITY_ACTIVE",
"reasons": [
  { "level": "stop", "code": "FREEZE_AUTHORITY_ACTIVE", "text": "the issuer can freeze your tokens so you can never sell" }
]

POST/v1/tokens

Up to 25 mints in one call. They run in parallel. One failed mint does not fail the batch: it comes back as { mint, error }.

curl -s -X POST "$BSOAD/v1/tokens" \
  -H 'content-type: application/json' \
  -d '{"mints":["EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm","DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"]}'

type BatchItem = Verdict | { mint: string; error: string };

const { results } = await bsoad<{ results: BatchItem[] }>('/v1/tokens', { mints });
for (const r of results) {
  if ('error' in r) console.warn(r.mint, r.error);
  else if (r.verdict !== 'ok') console.log(r.mint, r.verdict, r.code);
}

200

{ "results": [ Verdict | { "mint": "…", "error": "rpc unavailable: …" }, … ] }

400 {"error":"mints: 1-25 addresses"} when the list is empty, too long, or has a bad address.

POST/v1/simulate

Send the transaction a wallet is about to sign. bsoad finds the mints it touches, checks each one, and simulates the transaction itself. This is the call the extension makes before Phantom opens.

# TX = base64 of the serialized transaction
curl -s -X POST "$BSOAD/v1/simulate" \
  -H 'content-type: application/json' \
  -d "{\"tx\":\"$TX\",\"mints\":[\"EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm\"]}"

import { VersionedTransaction } from '@solana/web3.js';

// tx: the swap your terminal built, before the wallet signs it
async function preflight(tx: VersionedTransaction, outputMint: string) {
  const sim = await bsoad<Simulation>('/v1/simulate', {
    tx: Buffer.from(tx.serialize()).toString('base64'),
    mints: [outputMint],
  });
  if (sim.verdict === 'stop') throw new Error(sim.stopCode);
  if (sim.tx.fails) console.warn('this transaction fails:', sim.tx.error);
  return sim;
}

200, a real reply: 0.01 SOL into WIF through Jupiter, unsigned

{
  "verdict": "ok",
  "code": "CLEAN",
  "stopCode": "STOP: 0x0000B50AD CLEAN",  // built from the worst token's code
  "tx": {
    "fails": false,
    "error": null,                           // the simulation error as JSON when fails is true
    "logs": ["…", "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA success"]   // last 12 lines
  },
  "tokens": [ { "mint": "EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm", "verdict": "ok", "code": "CLEAN", "skipped": ["holders", "sell-sim"], … } ]
}

When the transaction fails and no token is worse than ok, verdict is warn and code is TX_FAILS.

• Up to 64 account keys are read. Up to 8 mints are checked.
• The simulation runs with signature checks off and a fresh blockhash.
• 400 when tx is missing or too short, or the bytes are not a transaction.

GET/v1/wallet/{addr}

Every token in a wallet now, plus tokens it held recently, each with a verdict. Up to 40 rows, held first.

• status: "held" means a balance above zero. "sold" means an empty token account, or a mint seen in recent history only.
• History reads the last 100 transactions through Helius when the server has a key, or the last 40 signatures over RPC.
• counts covers held rows only. A frozen token account turns its row into stop with YOUR_ACCOUNT_FROZEN.
• A row whose check failed has v: null and an error.

curl -s "$BSOAD/v1/wallet/J6hqWW8EqNMaGyv7ThZYCwoMM38FRotgKfpDp3FtUqB8?history=0"

const scan = await bsoad<WalletScan>(`/v1/wallet/${owner}`);
const traps = scan.tokens.filter((t) => t.status === 'held' && t.v?.verdict === 'stop');
console.log(`${traps.length} tokens in this wallet can trap you`);

200, a real reply (one row)

{
  "owner": "J6hqWW8EqNMaGyv7ThZYCwoMM38FRotgKfpDp3FtUqB8",
  "scannedAt": "2026-11-03T11:34:38.513Z",
  "tokens": [
    {
      "mint": "WXMRyRZhsa19ety5erZhHg4N3xj3EVN92u94422teJp",
      "amount": 1, "ui": 1e-12, "frozen": false, "emptyAccount": false,
      "status": "held",
      "v": { "verdict": "warn", "code": "MINT_AUTHORITY_ACTIVE", "reasons": [ … ], "skipped": ["holders", "sell-sim"], "meta": { "symbol": "XMR", … } }
    }
  ],
  "counts": { "held": 3, "stop": 0, "warn": 1 }
}

GET/v1/stream/wallet/{addr}

Server-sent events. The server scans the wallet, sends the full state, waits 30 s after each scan, and scans again. When a verdict flips, you get a change event right after that scan.

curl -N "$BSOAD/v1/stream/wallet/J6hqWW8EqNMaGyv7ThZYCwoMM38FRotgKfpDp3FtUqB8"

// Browser. EventSource cannot send headers, so the stream connects without a key.
const es = new EventSource(`${API}/v1/stream/wallet/${owner}`);

es.addEventListener('scan', (e) => {
  const scan: WalletScan = JSON.parse((e as MessageEvent).data);
  render(scan.tokens);
});
es.addEventListener('change', (e) => {
  const c: Change = JSON.parse((e as MessageEvent).data);
  if (c.to === 'stop') notify(`${c.mint} is now ${c.code}`);
});
es.addEventListener('error', (e) => {
  const data = (e as MessageEvent).data;     // set: the scan failed; unset: the connection dropped
  if (data) console.warn('scan failed:', JSON.parse(data).error);
});

• The first scan reads wallet history and can take a minute. Call GET /v1/wallet/{addr}?history=0 at the same time to paint held tokens sooner.
• Later scans list current token accounts only. Keep sold rows from the first scan on your side.
• One connection counts as one request against your limit.

POST/v1/keys

Get a free key: 120 requests a minute. The server keeps only a SHA-256 hash, so the key is shown once.

curl -s -X POST "$BSOAD/v1/keys" -H 'content-type: application/json' -d '{"label":"my bot"}'

# then send it on every call
curl -s -H "x-api-key: $BSOAD_KEY" "$BSOAD/v1/wallet/J6hqWW8EqNMaGyv7ThZYCwoMM38FRotgKfpDp3FtUqB8"

const { key } = await bsoad<{ key: string; tier: 'free'; limitPerMinute: number; note: string }>(
  '/v1/keys',
  { label: 'my bot' },                  // optional, up to 40 characters
);
// store it now: it cannot be shown again

201

{ "key": "bsoad_<24 characters>", "tier": "free", "limitPerMinute": 120, "note": "shown once, store it" }

The header is x-api-key. A ?key= query works too, but it ends up in logs. An unknown key is treated as no key.

GET/v1/health

Is the API up, and which RPC is it using. benched means that RPC answered 429 or 5xx and is skipped for now: 60 s for Helius, 4 s for others.

curl -s "$BSOAD/v1/health"

const h = await bsoad<{ ok: boolean; rpc: { rpc: string; benched: boolean }[] }>('/v1/health');
const live = h.rpc.filter((r) => !r.benched).length;

200, a real reply

{ "ok": true, "rpc": [
  { "rpc": "https://mainnet.helius-rpc.com/?api-key=…", "benched": false },
  { "rpc": "https://api.mainnet-beta.solana.com", "benched": false }
] }