API

Base URL & auth

All endpoints live under /api/v1 on this origin. Reads (health, catalog) are open. plan spends model credits, so it's rate-limited; pass an optional x-api-key to raise the ceiling. Keys are stateless (HMAC-signed), so there's nothing to leak server-side — but they only verify where a signing secret is set.

curl -s https://www.primeproto.xyz/api/v1/catalog

curl -s -X POST https://www.primeproto.xyz/api/v1/plan \
  -H 'content-type: application/json' \
  -H 'x-api-key: pk_...' \
  -d '{"message":"buy $50 of Tesla and stop me out below $200"}'

Live console

Every button below calls the real endpoint on this deploy and shows the actual response — status, latency, and body. If planning shows disabled, this deploy has no model key set (by design); run it against your own with ANTHROPIC_API_KEY.

Endpoints

The response

Every planned intent comes back with a verdict from the same deterministic check the chain enforces — an unknown ticker is refused here, before anyone acts on it.

{
  "message": "buy $50 of Tesla and stop me out below $200",
  "tier": "anon",
  "intents": [
    { "intent": { "kind": "spot_buy", "tokenOut": "dTSLA", "quoteToken": "USDG", "amountUsd": 50 }, "ok": true },
    { "intent": { "kind": "guardian", "token": "dTSLA", "trigger": "stop_loss", "priceUsd": 200 }, "ok": true }
  ]
}

The LLM Gateway

One self-describing front door to Prime's AI. GET /api/v1/llmreturns a manifest of what it can do; POST runs a capability. Its defining guarantee: every capability returns typed, validated output — never raw model text. An app built on it inherits Prime's safety invariants, so an unknown ticker is refused here before anyone acts on it. Same shared gate as /plan (an API key, or x402), and it reports your call count back.

Capabilities carry a cost. plan is model-backed (needs an API key or x402). parse, validate, anddescribe are free and deterministic — no model, no key, they work on the public deploy. Together they cover the intent lifecycle: parse a command into a typed intent, validate it against Prime's canonical rule (the same the chain enforces), and describe it for humans (tag, plain-English line, and when it takes effect).

curl -s $BASE/api/v1/llm                       # the capability manifest (free)

# free — parse a command into a typed intent (assets resolve by ticker/symbol/name):
curl -s -X POST $BASE/api/v1/llm -d '{"capability":"parse","input":{"command":"buy tesla 50"}}'
# -> { "output": { "command": "buy tesla 50",
#        "intent": { "kind": "spot_buy", "tokenOut": "dTSLA", "quoteToken": "USDG", "amountUsd": 50 }, "ok": true } }

# free — validate typed intents against Prime's rule:
curl -s -X POST $BASE/api/v1/llm -d '{"capability":"validate","input":{"intent":{ … }}}'

# model-backed — plan (x-api-key or x402):
curl -s -X POST $BASE/api/v1/llm -H 'x-api-key: pk_...' \
  -d '{"capability":"plan","input":{"message":"buy $50 of Tesla"}}'

Pay-per-call with x402 LIVE WHEN CONFIGURED

Besides an API key, /plan can be gated by x402— pay a few cents per call, no account. A keyless request gets a 402 with a signed-payment challenge; pay it and retry with an X-PAYMENT header, and we verify + settle through a facilitator before serving. We never take custody — settlement is peer-to-contract on-chain; this server only checks the receipt. Off unless a facilitator, recipient, asset, and price are configured (/healthreports x402).

# 1. keyless request → 402 with the payment requirements
curl -i -X POST $BASE/api/v1/plan -d '{"message":"buy $50 of Tesla"}'
# HTTP/1.1 402 Payment Required
# { "x402Version": 1, "accepts": [ { "scheme": "exact", "asset": "USDG", "maxAmountRequired": "10000", "payTo": "0x…" } ] }

# 2. pay, then retry with the signed authorization
curl -X POST $BASE/api/v1/plan -H "x-payment: <base64 payment>" -d '{"message":"buy $50 of Tesla"}'
# 200 OK  ·  X-PAYMENT-RESPONSE: <base64 receipt with the settlement tx>

Self-hosting the full platform

The public deploy runs reads only. To run planning and issue keys, set three env vars and the same code lights up — /health will report it:

• ANTHROPIC_API_KEY — turns on /plan.
• PRIME_API_SECRET — the HMAC signing secret; makes keys verifiable.
• PRIME_ADMIN_SECRET — the bearer that authorizes /keys to mint.
• PRIME_X402_* — a facilitator URL, recipient, asset, and price turn on x402 pay-per-call.

# mint a key (self-host)
curl -s -X POST http://localhost:3001/api/v1/keys \
  -H 'authorization: Bearer $PRIME_ADMIN_SECRET' \
  -H 'content-type: application/json' \
  -d '{"tier":"pro"}'

Webhooks LIVE WHEN CONFIGURED

Push events instead of polling. The management API (/api/v1/webhooks) and the signing + delivery worker are built and tested; they turn on where a DATABASE_URL and signing key are set (the indexer's Postgres), so this public deploy honestly reports webhooks:false and returns 503. Every event is a pure projection of an indexed on-chain row — no invented fields, stable ids, replay-identical.

Register an endpoint, subscribe to events, and fire a test ping the worker signs and delivers — each endpoint scoped to your API key:

curl -s -X POST $BASE/api/v1/webhooks -H "x-api-key: pk_..." \
  -H 'content-type: application/json' \
  -d '{"url":"https://you.example/hook","events":["trade.executed","pnl.realized"]}'
# -> { id, secret }   (the signing secret is shown once)

curl -s -X POST $BASE/api/v1/webhooks/$ID/test -H "x-api-key: pk_..."   # deliver a webhook.ping

Each delivery is HMAC-signed (the same discipline as API keys), timestamped against replay, retried with backoff, and idempotent on a stable event id:

X-Prime-Signature: t=1786012801,v1=<hex hmac_sha256(secret, `${t}.${rawBody}`)>

# verify: recompute the HMAC over `${t}.${rawBody}`, constant-time compare,
# and reject if |now - t| > 300s. At-least-once delivery — dedupe on X-Prime-Id.