ZendIQ-Agent-API

# 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](#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:

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

PowerShell:

```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):

```python
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 16 `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.

```bash
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):

```bash
npm run analyse
```

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

```bash
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](#connect-it-to-an-agent-mcp).

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:

```bash
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](#execution--build-a-signable-swap-optimize).

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](https://zendiq.ai/agents/#latency).

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](https://zendiq.ai/agents/#settlement).

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](https://zendiq.ai/agents/#redeem).

## 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:

```js
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.

| Input | Type | Required | Description |
|---|---|---|---|
| `mint` | string | yes | Base58 mint of the token to screen |

**`zendiq_triage_swap`** — **decide** stage. Call it before signing a swap, to decide whether and how to trade it. Paid. Retu