API Reference — Intercept Docs

This page describes the planned HTTP API. No endpoint is live. The base URL below is a placeholder that does not resolve to a real service, and the request and response shapes may change before release.

Basics

Item	Value
Base URL	`https://api.intercept.example/v0` (placeholder, not a real endpoint)
Auth	`Authorization: Bearer <api key>`
Content type	`application/json`
Idempotency	Optional `Idempotency-Key` header on every `POST` and `PUT`
Transactions	Base64-encoded serialized Solana transactions

A request with a valid key always receives a decision or a transport error. A blocked decision is a successful 200 response, not an error. See Error Handling.

POST /v0/evaluate

Simulates a transaction and evaluates it against the agent's active policy. Does not send anything onchain.

Request:

JSON

{
  "agentId": "agent_7f3c",
  "transaction": "<base64-serialized-transaction>",
  "intent": "Swap 1,200 USDC to SOL on Jupiter"
}

Response 200:

JSON

{
  "evaluationId": "ev_01HX...",
  "decision": "blocked",
  "policyVersion": "0.1",
  "reasons": [
    { "code": "RISK_MAX_LEVERAGE", "layer": "risk", "message": "Resulting leverage 4.2x exceeds maxLeverage 3x." }
  ],
  "simulation": { "success": true, "computeUnits": 182340, "balanceChanges": [] },
  "latencyMs": 41
}

POST /v0/execute

Submits an approved evaluation. In enforced mode, Intercept co-signs only if the transaction matches the evaluated bytes and the evaluation has not expired.

Request:

JSON

{
  "evaluationId": "ev_01HX...",
  "transaction": "<base64-serialized-transaction>"
}

Response 200:

JSON

{ "evaluationId": "ev_01HX...", "signature": "<transaction-signature>", "status": "submitted" }

Returns 409 if the evaluation is not approved, has already been executed, or the transaction differs from the evaluated one.

GET /v0/evaluations/{id}

Returns a stored evaluation, including its current decision. Useful after a requires_approval decision has been resolved.

Response 200: the evaluation object above, plus:

JSON

{ "executedAt": null, "approval": { "status": "pending", "requestedAt": "2026-11-15T10:02:11Z" } }

POST /v0/approvals/{id}

Requests or records human approval for a requires_approval evaluation. {id} is the evaluation ID.

Request (agent requesting):

JSON

{ "action": "request", "note": "Rebalance above 50k threshold" }

Request (approver responding):

JSON

{ "action": "approve", "approver": "<approver-pubkey>", "signature": "<ed25519-signature>" }

action is request, approve or reject. Response 200:

JSON

{ "evaluationId": "ev_01HX...", "approval": { "status": "approved" }, "decision": "approved" }

PUT /v0/policies/{agentId}

Validates and publishes a policy. Send ?dryRun=true to validate only.

Request: the full contents of intercept.policy.json. See Configuration.

Response 200:

JSON

{ "agentId": "agent_7f3c", "policyVersion": "0.1", "publishedAt": "2026-11-15T10:00:00Z" }

Response 422:

JSON

{ "error": "SYS_POLICY_INVALID", "errors": [ { "path": "risk.maxLeverage", "message": "must be >= 1" } ] }

POST /v0/agents/{agentId}/pause

Pauses the agent. Every subsequent evaluation returns blocked with SYS_PAUSED.

Request: { "reason": "Investigating unexpected drawdown" } Response 200: { "agentId": "agent_7f3c", "paused": true, "pausedAt": "2026-11-15T10:05:00Z" }

POST /v0/agents/{agentId}/resume

Resumes a paused agent.

Request: {} Response 200: { "agentId": "agent_7f3c", "paused": false, "resumedAt": "2026-11-15T11:00:00Z" }

Status codes

Code	Meaning
`200`	Success. For `evaluate`, any decision, including `blocked`
`400`	Malformed request or undecodable transaction
`401`	Missing or invalid API key
`403`	Key not authorized for this agent
`404`	Unknown agent or evaluation
`409`	Conflict: evaluation not executable, or idempotency key reused with a different body
`422`	Policy failed validation
`429`	Rate limited; honor `Retry-After`
`5xx`	Server error; treat as fail-closed and retry with the same idempotency key

curl example

Shell

# Placeholder URL — this endpoint does not exist yet.
curl -X POST https://api.intercept.example/v0/evaluate \
  -H "Authorization: Bearer $INTERCEPT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d9f2c1e-4b0a-4e6f-9a51-2f1c0c8e3b77" \
  -d '{
    "agentId": "agent_7f3c",
    "transaction": "<base64-serialized-transaction>",
    "intent": "Swap 1,200 USDC to SOL on Jupiter"
  }'