ZendIQ README

ZendIQ Agent API

ZendIQ gives agents a paid, machine-readable Solana swap triage verdict before they sign. The public surface includes the MCP client, x402 client, budget controls, response contract, and a runnable example.

What's open, and what isn't

This repository contains the complete agent-facing integration surface:

• MCP server exposing zendiq_screen_token, zendiq_triage_swap and zendiq_optimize_swap
• x402 payment client
• Execution client — build, verify, and submit an optimized unsigned swap (/optimize)
• Autonomous candidate feed and triage loop
• Decision ledger with a hard local spend ceiling
• Public request and response contract
• Payment network read from the live API (GET /v1/agent), with a required spend ceiling on mainnet

The scoring model is intentionally not included. Each response surfaces the individual signals, their observed values, their status, and each factor's point contribution to the score — so an agent can act on any single signal (for example, refuse on a serial-deployer flag) rather than only the headline verdict. But how those signals are derived and combined — the data sources, thresholds, and weighting model — runs behind the hosted /analyse endpoint and remains ZendIQ's proprietary engine. The contract is open so integrators can inspect exactly what is sent, returned, paid for, and acted on.

This repository contains no extension analytics, user telemetry, production deployment configuration, database schema, facilitator wallet, or production credentials. It has fresh history independent of ZendIQ's private backend.

Requirements

• Node.js 22.5 or newer
• A Solana keypair holding mainnet USDC for paid calls (it needs no SOL)
• Network access to ZendIQ's hosted API at https://api.zendiq.ai, where scoring runs — see Where your calls go before running anything.

Quickstart

Start free, with nothing installed. Screening a token needs no wallet, no payment, no key and no clone. This returns a real risk score, usually in a few seconds:

curl -s -X POST https://api.zendiq.ai/v1/agent/analyse-token \
  -H "content-type: application/json" \
  -d '{"mint":"JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"}'

PowerShell:

Invoke-RestMethod -Method Post https://api.zendiq.ai/v1/agent/analyse-token `
  -ContentType 'application/json' `
  -Body '{"mint":"JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"}' | Select-Object -ExpandProperty tokenRisk

Python (standard library only):

import json, urllib.request

req = urllib.request.Request(
    "https://api.zendiq.ai/v1/agent/analyse-token",
    data=json.dumps({"mint": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"}).encode(),
    headers={"content-type": "application/json"},
)
with urllib.request.urlopen(req, timeout=30) as resp:
    body = json.load(resp)

risk = body["tokenRisk"]
print(risk["symbol"], risk["score"], risk["level"], "signals", body["signals_resolved"])

The response holds tokenRisk (score and level), the 17 signals behind it with coverage in signals_resolved, and an analysisId that /optimize can reuse for 60 s.

Paid calls. The steps below run on your machine. The only calls to ZendIQ are the scoring and /optimize requests to the hosted API; no URL needs setting for those. The npm commands are the same in bash and PowerShell.

1. Install and set a local spend ceiling. budget:init reads the payment network from the API (GET /v1/agent, free) and writes a $1.00 ledger for it under runtime/. It spends nothing. On mainnet every payment is reserved against this ceiling, and nothing here pays without one.

npm ci
npm run budget:init

2. Provide and fund the paying key. This code never generates or writes a mainnet key. Put a Solana keypair you control at runtime/payer-mainnet.key.json: any file solana-keygen writes, for example solana-keygen new -o runtime/payer-mainnet.key.json. Fund its address with a little USDC on Solana mainnet. No SOL is needed: the x402 facilitator pays the payment's network fee. $1 covers 100 calls at $0.01. Use a dedicated wallet, because the ledger only bounds what is paid through this code.

3. Make one paid call ($0.01 in mainnet USDC):

npm run analyse

4. Run the MCP server with the same key and ledger:

npm run mcp

Or skip the clone entirely: npx -y @zendiq/mcp@latest runs the same server from npm. See Connect it to an agent.

The MCP server uses newline-delimited JSON-RPC over stdio. Diagnostics go to stderr so stdout remains a valid MCP transport.

5. Optional: try /optimize build-only. /optimize builds a mainnet swap for a taker. The taker is only a public key and nothing is signed, so any funded mainnet address shows the full plan, simulation and venue decision. For the default 0.003 SOL swap, pick one holding a little more than 0.003 SOL:

npm run optimize -- --taker <ANY_FUNDED_MAINNET_ADDRESS>

This is build-only: it pays $0.02 in USDC and signs nothing, and you cannot sign a transaction built for a wallet you do not control. A taker that cannot fund the trade gets 422 taker_insufficient_balance, uncharged. To land a trade, see Execution.

Set variables in your shell. Nothing in this repository loads a .env file; .env.example only lists the variables for reference.

The first scan of a token typically takes 1–5 s and at most about 12 s; a token scanned by anyone in the last 60 s comes back in under a second. Details: How long a call takes.

A paid call can also hold its response for up to 90 seconds while payment settlement is confirmed on chain, which happens when the facilitator cannot confirm the transfer itself. Allow at least 120 seconds on /analyse and /optimize. MCP hosts often time out a tool call sooner; raise that limit if your host allows it. Details: Settlement can hold the response.

If that ends in 402 with settlement_pending, keep the payment header and retry once with the same header: a payment that landed late is redeemed for one fresh response on the same route, within 24 h. zendiq-client.js and the MCP server do this for you. Details: Retry once after settlement_pending.

Where your calls go

Runs on your machine: the MCP server (a local stdio adapter), x402 payment signing, the budget ledger, the candidate feed, the triage loop, transaction verification and signing, and the demo visualizer.

Calls ZendIQ's hosted API: token screening, /analyse and /optimize. The scoring engine is not in this repository and has no local mode — every score comes from the hosted API.

Calls third parties directly: DexScreener (candidate feed), Jupiter /execute and a Solana RPC (only when you pass --execute), and the x402 facilitator (payment settlement).

The default endpoint is ZendIQ's live hosted API. If you clone this repo and run it without setting a URL, your calls hit our production service and are billed as real x402 payments:

const BASE_URL = process.env.ZENDIQ_API_URL ?? 'https://api.zendiq.ai';

That default is deliberate — it makes the quickstart work without infrastructure. It is not a sandbox. Two consequences worth understanding before you run a loop:

• Payments are real settlements in mainnet USDC: $0.01 per /analyse, $0.02 per /optimize. They are on-chain transactions, not mocks.
• npm run watch is an autonomous loop. It pays per candidate until the local budget ceiling stops it. Set budget:init deliberately; it is the only thing bounding spend.

The endpoint can be overridden — ZENDIQ_AGENT_URL for the MCP server, ZENDIQ_API_URL for the examples and the demo runner — but it must point at a ZendIQ Agent API. These are two separate variables reading two separate code paths; setting one does not affect the other. The demo runner is the exception: it passes its ZENDIQ_API_URL to the MCP server it spawns, so there ZENDIQ_AGENT_URL is ignored.

Payment rail: the examples, budget:init and the demo runner read the payment network from the API (GET /v1/agent, field network). AGENT_NETWORK is optional; if set, it must agree with the API or they refuse to run. budget:init is the exception: an explicit AGENT_NETWORK is taken as given there, so a ledger can be created before a server switches. The MCP server reads ZENDIQ_AGENT_NETWORK, which defaults to mainnet; any value other than mainnet or devnet makes its paid tools refuse. The hosted API settles in mainnet USDC, analyses mainnet, and /optimize returns a real mainnet transaction.

No ZendIQ credentials ship in this repository. The paying key is yours, signs your payments, and never leaves your machine.

Connect it to an agent (MCP)

The server speaks the Model Context Protocol over stdio (newline-delimited JSON-RPC), so any MCP-capable client — Claude Desktop, Cursor, Cline, or your own harness — can call it directly. It exposes three tools, one per workflow stage. They are independent entry points, not a required sequence: call whichever matches the question you actually have.

zendiq_screen_token — screen stage. Call it first, whenever you are considering a token and have no trade yet (an agent scanning many fresh mints has none). Free and rate-limited, cacheable across callers. Returns the token risk score, its signal breakdown, signals_resolved coverage, and a cache block (hit, ageSeconds, observedAt) so you can decide whether to force fresh.

zendiq_triage_swap — decide stage. Call it before signing a swap, to decide whether and how to trade it. Paid. Returns the full token score inline (so screening first is optional, never required), plus sandwich exposure, the route and the recommended execution. Builds no transaction.

Output (structuredContent):

• verdict — Safe (route normally), Protect (route through a Jito bundle), or Refuse (do not execute)
• recommendedExecution — { path, priorityFeeLamports, jitoTipLamports }
• reasons — plain-language justification

The full risk breakdown (token-risk factors, sandwich exposure, provenance fingerprint) is returned unchanged alongside these committed fields, so the MCP result is byte-identical to the HTTP /analyse response. Each call costs $0.01 in USDC, paid automatically via x402 using the configured keypair.

zendiq_optimize_swap — execute stage. Call it once you have decided to trade and need the transaction. Paid. Returns an unsigned swap transaction (the Jupiter route, or a direct venue or Jito bundle that beats it after every cost by more than 0.1% of the trade, capped at $1), the plan to verify it against, submit instructions, a simulation, an itemised netBenefit, and the same verdict as zendiq_triage_swap. Zero custody — nothing is signed here.

This tool also returns the Safe / Protect / Refuse verdict and its reasons, the same as zendiq_triage_swap, but it builds the transaction even on a Refuse, because it assumes the decision to trade has been taken. Read verdict before signing. Each call costs $0.02 in USDC; a build that fails charges nothing.

Payment settles in mainnet USDC from the paying wallet, and the swap is routed against mainnet liquidity for taker. The API accepts the paying wallet as taker; the examples here keep the two keys apart and refuse a taker key that is the payer.

Register it in your MCP client's config. The package runs straight from npm, with no clone. In Claude Code it is one command:

claude mcp add --scope user zendiq -- npx -y @zendiq/mcp@latest

For any other client, paste the JSON below into its user config (~/.claude.json for Claude Code, or the client's own config file), which connects straight away. A project .mcp.json works too, but the client asks you to approve the server first.

{
  "mcpServers": {
    "zendiq": {
      "command": "npx",
      "args": ["-y", "@zendiq/mcp@latest"]
    }
  }
}

That is enough for zendiq_screen_token, which is free and needs no wallet. The paid tools need two more things, both kept in ~/.zendiq (or AGENT_STATE_DIR):

1. A spend ceiling: npx -y @zendiq/mcp@latest budget init 1.00 writes budget-mainnet.json. It spends nothing. npx -y @zendiq/mcp@latest budget shows what has been spent.
2. A paying key holding mainnet USDC at ~/.zendiq/payer-mainnet.key.json: any file solana-keygen writes, for example solana-keygen new -o ~/.zendiq/payer-mainnet.key.json. It is never generated for you. At startup the server logs the paying address and the file it came from to stderr.

The server refuses to keep keys or the ledger inside node_modules or the npx cache, because npm deletes those folders without warning and a funded key there would be lost.

From a clone, point the client at the file instead (paths must be absolute):

{
  "mcpServers": {
    "zendiq": {
      "command": "node",
      "args": ["/absolute/path/to/ZendIQ-Agent-API/src/mcp-server.js"]
    }
  }
}

There the key and ledger default to runtime/ beside the clone, as for the examples.

On mainnet the paying key is only loaded together with a mainnet ledger.

Diagnostics go to stderr so stdout stays a clean JSON-RPC transport. Transport is stdio only — the standard local MCP transport every client supports; a remote/HTTP transport is not currently provided.

To sanity-check the wiring without a client, drive it by hand — initialize then tools/list need no keypair or payment:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | npx -y @zendiq/mcp@latest

PowerShell:

'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}',
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | npx -y @zendiq/mcp@latest

Autonomous agent

The complete test agent is public under examples/. It watches DexScreener's live Solana boost feed, enriches each candidate, pays ZendIQ for a verdict, and records whether it would refuse, protect, or route the trade normally.

npm run budget:init
npm run feed
npm run watch

watch begins with USDC as a control, so a run proves that the agent discriminates rather than refusing everything. It then prints a run ledger containing triage spend, refused candidates, protected candidates, and candidates cleared for direct routing.

The autonomous agent is advisory — it reports the recommended path and fees without claiming that money moved. To build and submit a real optimized swap, see Execution below. Keys and budget ledgers live under the gitignored runtime/ directory.

What the budget ceiling guarantees

The ledger (examples/budget.js) is a hard ceiling on what the paying wallet spends on ZendIQ calls. It holds under these conditions, and only these:

• What it counts. Every x402 payment made through ZendIQClient: the examples, the demo runner, and the MCP server, which all share that one payment path. Each payment is reserved before it is signed and resolved afterwards. An outcome that might have been charged is counted as spent, so the ceiling over-counts rather than under-counts.
• On mainnet the paying key is fenced.
  • It is loaded only by loadAgentSigner, from its own file, runtime/payer-mainnet.key.json, and only with a mainnet ledger attached; without one it throws.
  • Advanced override for CI: AGENT_SECRET_SEED takes the paying key as a JSON array of exactly 32 bytes (a seed). If a key file is also present and holds a different key, nothing starts and both addresses are printed.
  • A ledger records the one key that pays against it, and a key is bound to one ledger.
  • The wallet a swap is built for (--taker, ZENDIQ_TAKER_KEYPAIR) is a separate key, and it is refused if it is the payer.
• More than one process may share a ledger. Every change takes a lockfile (<ledger>.lock, holding the owner's PID) and re-reads the file, so two processes cannot both reserve the same remaining budget.
• A crashed process does not wedge the ledger. If the lock holder is killed mid-operation, the next spender sees that its PID is gone and takes the lock over at once. If the holder is still alive, the spender waits up to 5 s and then refuses to pay. The error names the PID and the lockfile; it never hangs. A lock older than 30 s is taken over regardless. Manual recovery: stop every agent using that ledger, then delete <ledger>.lock.
• What it cannot see:
  • Anything signed with the paying key outside this code, for example a script that reads the key file itself.
  • The funding transfer into the paying wallet, and any later top-ups.
  • Network fees and token-account rent. The facilitator pays the payment's network fee, so in normal use the paying wallet spends USDC only.
  • Swaps, which the taker signs and pays for, from a different wallet.

What "exact reconciliation" means. Compare two lists for one paying address: every USDC transfer out of that address on chain, and every ledger entry in state settled, matched by transaction signature (the entry's note, which holds the settlement signature from the server's PAYMENT-RESPONSE). For a key used only through this code they match one to one. The single expected exception is a settled entry noted unconfirmed_settlement_may_have_landed, which may have no transfer, because the ledger counts a payment it cannot rule out. Inflows (funding, top-ups) are not ledger entries and are not part of the comparison. Any outflow with no matching entry means the key was used outside the ledger.

Reconciling a fresh key

1. Generate the key and fund it with USDC. Record the funding transaction's signature; it is the only expected inflow.
2. Create a new ledger for it (AGENT_NETWORK=mainnet node examples/budget.js init <ceilingUsd>). Never point a new key at a ledger that already has entries: its history belongs to another key and can never reconcile. init refuses to overwrite an existing file, so move an old one aside first.
3. Make paid calls only through this code. The first load binds the key to the ledger (payer in the ledger, runtime/payer-bindings.json).
4. List the paying address's USDC token-account history on chain. Drop the funding transfer and any top-ups. The remaining outflows' signatures must equal the note signatures of the ledger's settled entries, and their amounts must equal each entry's atomic (USDC, 6 decimals).

Execution — build a signable swap (/optimize)

/analyse is advisory. /optimize goes one step further: it returns an unsigned swap transaction, with the venue, priority fee and MEV posture chosen from the same risk model and a net-benefit comparison across venues — plus the plan, an on-chain simulation, and the net-benefit arithmetic. You verify the bytes against the stated plan, then sign and submit with your own wallet. ZendIQ never holds a key.

npm run budget:init
# Stop at simulation — pays $0.02 USDC, prints the plan + simulation, signs nothing:
npm run optimize -- --taker <YOUR_MAINNET_PUBKEY>

# Real landing — signs the returned tx and submits it as the response's submit block directs:
export ZENDIQ_TAKER_KEYPAIR=/path/to/mainnet-keypair.json
npm run optimize -- --taker <YOUR_MAINNET_PUBKEY> --execute

In PowerShell, set the key path with $env:ZENDIQ_TAKER_KEYPAIR = 'C:\path\to\mainnet-keypair.json' instead of export.

The swap routes on mainnet, so --taker must be a wallet that holds the input amount and SOL for fees and rent; the x402 payment is a separate USDC transfer from the paying wallet. By default the example stops at simulation and spends nothing on-chain — pass --execute (with ZENDIQ_TAKER_KEYPAIR) to sign and land a real swap. On jupiter_ultra the example submits through Jupiter's /execute; on jupiter_swap it sends through SOLANA_RPC_URL, which defaults to the public mainnet RPC; on a Jito bundle venue it posts the signed transaction to ZendIQ's /v1/agent/bundle and polls until it lands. The response carries the unsigned transaction, the plan, the submit instructions for the chosen venue, the simulation result, and the netBenefit breakdown — everything needed to confirm the transaction matches the stated intent before signing.

The example also prints the verdict and the venue decision. The venue decision lists every candidate with its net value, priority fee, Jito tip, modelled sandwich cost and bundle landing risk, the margin it had to beat, and why the winner won. It is plan.venueDecision from the response, so an agent can check the choice rather than trust it. With --execute the example will not sign a trade whose verdict is Refuse, just as it will not sign one whose simulation failed; pass --sign-refused to override it.

Demo visualizer

A local spectator view that renders one real swap-triage call as a live, animated sequence across two transports side by side — the MCP agent tool and the direct x402 HTTP rail — then verifies that both returned the same token-risk evidence fingerprint. It then runs /optimize for the same swap and shows the execution sequence — Optimize → Sign → Land — ending at an on-chain simulation (or a real mainnet landing with --execute). Every value on screen is real: live risk score, real USDC settlement, real transaction. Nothing is staged.

Prerequisites

• Node.js 22.5+ and npm ci already run.
• The funded paying key and budget ledger from the Quickstart, steps 1–2. The runner uses the same runtime/payer-mainnet.key.json and runtime/budget-mainnet.json; the key signs USDC payment authorizations only and never leaves your machine (runtime/ is gitignored). No SOL is required. The runner never creates a mainnet ledger itself.
• The visualizer and runner run locally; the calls they display go to the hosted API. The runner reads ZENDIQ_API_URL and hands the same URL to its MCP lane, so ZENDIQ_AGENT_URL has no effect here.

Run it

Start the visualizer in one terminal:

npm run demo

Open http://127.0.0.1:4173, then in a second terminal:

npm run demo:run -- --mint JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN --taker <YOUR_MAINNET_PUBKEY>

To finish with a real on-chain landing, add --execute and set ZENDIQ_TAKER_KEYPAIR to the mainnet keypair for --taker. Without --execute, the execution lane stops at simulation and spends nothing on-chain.

Both lanes fill in — request → 402 → USDC authorization signed → payment settled → analysis returned — and the footer shows Verified · identical token-risk evidence with the shared fingerprint. The fingerprint covers the deterministic token screening (mint, score, level, signals, inputs); the live route economics shown per lane (sandwich exposure, price impact) are re-fetched on each call and can drift a fraction of a percent with price movement between the two sequential requests. The runner exits 0 on a fingerprint match, non-zero on mismatch. The event stream deliberately excludes payment authorizations, secrets, RPC URLs, and complete wallet addresses.

Troubleshooting

• Preflight failed / fetch failed — the runner needs both the Agent API and the visualizer (npm run demo) up at the same time. Start the visualizer first and leave it running.
• Payment was rejected — the paying wallet holds too little mainnet USDC. Fund it (Quickstart, step 2) and re-run; a rejected payment is never charged.
• UI stays on "Waiting for an agent call…" — the page is passive; it only fills once demo:run emits events. Confirm the runner printed Demo complete.

Contract

The complete machine-readable contract is openapi.json (OpenAPI 3.1): every endpoint, request body, response shape, error code, and worked examples. It is the same file served at https://zendiq.ai/openapi.json. For the live prices, rate limits and field-stability tiers, GET /v1/agent on the API is authoritative. The summary below covers what most integrations need.

POST /v1/agent/analyse-token — free, rate-limited (screen stage)

{ "mint": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN" }

Screen a token by mint, with no trade size. Returns the token risk score, its signal breakdown, signals_resolved coverage, and a cache block (hit, ageSeconds, observedAt) — a cached score reports the slot and time it was computed at, never the current one. No payment; rate-limited per IP.

POST /v1/agent/analyse — paid (decide stage)

{
  "inputMint": "So11111111111111111111111111111111111111112",
  "outputMint": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN",
  "amount": "500000000",
  "slippageBps": 100
}

Stable response fields:

• verdict: Safe, Protect, or Refuse
• recommendedExecution.path
• recommendedExecution.priorityFeeLamports
• recommendedExecution.jitoTipLamports
• reasons
• disclaimer

Additional fields are experimental and may change within v1. Stable fields are additive-only within v1; breaking changes ship under a new API version.

POST /v1/agent/optimize

Same request body as /analyse plus a taker public key. Returns an unsigned swap transaction, the plan (venue, slippage, priority fee, and the venueDecision comparison behind the venue), a simulation result, the netBenefit breakdown, and the same verdict, confidence and reasons as /analyse. Zero custody — you verify, sign, and submit. Priced per call in USDC.

The venue is chosen by risk, so read plan.venue rather than assuming one. Jupiter Ultra is used for low-risk trades and for sandwich-driven risk, where its upstream MEV protection is the instrument that addresses the exposure; it sizes the priority fee itself. The Jupiter Swap API (Quote + Build) is used when risk scoring calls for a specific priority fee, which Ultra cannot honour — there plan.priorityFee reports the fee actually applied, read back out of the build, and the route carries no upstream MEV protection.

A direct venue is quoted alongside and replaces the Jupiter route only when it beats it after every cost: priority fee, Jito tip, expected sandwich loss, and for a bundle its landing risk (an assumed 5% chance of paying for a rebuild). It must win by a margin of 0.1% of the trade, capped at $1: enough that quote noise cannot flip the venue, small enough that a real saving still wins. Unprotected Raydium competes only on a Safe verdict. The Jito bundle venues (Raydium + Jito, Jupiter Swap + Jito) compete on every verdict; on Safe they step aside while ZendIQ's shared Jito submission budget is busy, so protected trades keep it. plan.venueDecision shows every candidate's arithmetic; often the answer is Jupiter.

Submission differs by venue — follow the returned submit object rather than hardcoding a path. On jupiter_ultra, sign transaction and POST { signedTransaction, requestId } to the URL in submit.url (today https://lite-api.jup.ag/ultra/v1/execute). Take it from each response: an Ultra order can only be executed on the Jupiter gateway that issued it, and the host is expected to move to api.jup.ag/swap/v2. The example client follows submit.url and refuses any URL that is not a known Jupiter /execute endpoint. Submitting through your own RPC instead forfeits Ultra's MEV protection and invalidates the netBenefit figures. On jupiter_swap and raydium there is no requestId (it is null) and no /execute step — sign and send to your own RPC, with the priority fee already inside the transaction. Send a raydium transaction promptly: Raydium embeds its own blockhash and submit.lastValidBlockHeight is null. On a Jito bundle venue (submit.method: "jito_bundle"), sign and POST { "signedTransaction": "<base64>" } to /v1/agent/bundle on this API (free): ZendIQ forwards those exact bytes to Jito and reports landing. Never send a bundle transaction to an RPC yourself; it would sit in the public mempool and still pay the tip.

netBenefit.netUsd = expectedMevLossUsd − zendiqFeeUsd − jitoTipUsd − jupiterPlatformFeeUsd − priorityFeeUsd: the sandwich loss the route avoids, less every fee you pay to execute it. It is stated only on routes that claim MEV protection (Jupiter Ultra and the bundle venues). jupiterPlatformFeeUsd is Jupiter's own fee on an Ultra trade (0–50 bps by pair, 2 bps on SOL–USDC; already inside the quoted amounts) and 0 elsewhere. priorityFeeUsd is decoded from the transaction: what your taker pays, 0 on a bundle or a gasless fill. The 5,000-lamport base signature fee is the same on every route and is not included. When a cost cannot be priced, netUsd is null and netUsdBasis says why.

/optimize returns the same verdict (Safe / Protect / Refuse) as /analyse but does not refuse to build: a Refuse still comes back with a transaction, even for a token that scores CRITICAL. Read verdict and tokenRisk before signing, and do not sign a Refuse unless you mean to trade against it.

When token screening does not complete

One rule covers every endpoint. A slow or failing source never fails the call: that one check comes back unknown inside a completed, scored 200, and an unknown adds caution points rather than counting as a pass. A call returns 502 analysis_unavailable, and is not charged, only when no honest answer is possible: on any of the three when a mint cannot be confirmed, on /analyse-token when no score can be produced at all, and on /analyse when neither the route nor the screening could be retrieved. /optimize returns 502 optimize_unavailable, also not charged, when it cannot build a transaction.

If screening as a whole does not complete on /analyse or /optimize but the route does, the call still returns 200, and the gap is explicit, never a clean-looking score:

• tokenRisk is { mint, available: false, error, assumedScore: 50, assumedLevel: "HIGH", note }, with no score or level.
• Fees and overall risk are sized as if the token scored HIGH, not as if it scored 0.
• /analyse fails closed: verdict is Protect with confidence: "low", degraded contains token_screening:<reason>, and reasons states that screening did not complete. A Protect reached this way means the token was not checked, not that it was found risky.
• /optimize still returns a transaction. The example prints token risk UNAVAILABLE and warns before signing, but does not refuse — check tokenRisk.available yourself if your agent should.

Security

Never commit keypairs, seeds, .env, budget ledgers, or RPC URLs containing credentials. This repository configures a mandatory pre-push secret scan through .githooks/pre-push; install either gitleaks or trufflehog before pushing.