Developers

Plutus API

A small REST surface for agents to transact and for operators to provision. Settlement rails are simulated in this demo; the contract is real. Authenticate with a Bearer API key (issued in Settings → API keys). Scopes: AGENT_AUTHORIZE, READ_ONLY, ADMIN_FULL.

Authorize a spend

POST/api/v1/authorize

The synchronous decision endpoint. Returns APPROVE, DENY, or ESCALATE with the rule that governed it. Idempotent on idempotencyKey.

curl -X POST https://plutus.demo/api/v1/authorize \
  -H "authorization: Bearer pk_live_…" \
  -H "content-type: application/json" \
  -d '{
    "envelopeId": "env_task_research",
    "credentialId": "cred_research",
    "amount": 4200,                 // minor units ($42.00)
    "currency": "USD",
    "goal": "Competitive pricing dataset",
    "merchant": { "name": "Exa", "mcc": "4899", "acceptsStablecoin": true }
  }'

→ 200
{
  "transactionId": "txn_…",
  "decision": "APPROVE",
  "status": "SETTLED",
  "rail": "STABLECOIN",
  "reasonCode": "OK",
  "settlement": { "rail": "STABLECOIN", "providerRef": "usdc_0x…", "feeFormatted": "$0.00" }
}

Read

GET/api/v1/agents/me

The KYA identity and Plutus Score of the agent bound to the key.

GET/api/v1/transactions/:id

Poll a transaction - useful to learn an escalation's outcome.

GET/api/v1/envelopes/:id

Envelope balances: allocated, committed, spent, available.

POST/api/v1/transactions/:id/refund

Refund a settled transaction (admin scope). Body: { "amount": 2100 } for partial, or omit for full.

Settlement rails

One mandate, three rails. The agent never chooses - the router prefers the cheapest native rail the merchant accepts.

x402 - HTTP-native, instant, zero fee. Payment as an HTTP 402 Payment Required response; the agent settles inline. Preferred for APIs and digital services.
stablecoin - USDC, instant finality, zero interchange.
card - the legacy long tail; auth + clearing with interchange.

Decline reason codes

Declines are structured so an agent can reason about them - not a bare "declined."

AMOUNT_EXCEEDS_TXN_CAPAbove the per-transaction cap

ENVELOPE_EXHAUSTEDBudget envelope has no available balance

ROLLING_WINDOW_CAP_EXCEEDEDWould exceed a rolling spend window

CATEGORY_BLOCKED / CATEGORY_NOT_ALLOWEDMerchant category disallowed

COUNTERPARTY_SANCTIONED / _TOO_NEW / _RISK_TOO_HIGHCounterparty failed checks

CREDENTIAL_EXPIRED / CREDENTIAL_REVOKEDCredential is not active

TRUST_TOO_LOWAgent trust below the floor

ABOVE_ESCALATION_THRESHOLDHeld for human approval (ESCALATE)