ZendIQ

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.

| taker | string | yes | Base58 mainnet wallet the swap is built for; must hold the input amount and SOL for fees and rent (a gasless Jupiter Ultra fi