API: Allowances

Request payment

POST /v1/payments/request

Attempts to settle a payment from one agent allowance.

{
  "agentId": "researchbot-01",
  "service": "risk-report-api",
  "amount": "0.03",
  "asset": "USDC",
  "reason": "Fetch risk report",
  "metadata": {
    "requestId": "risk_992"
  }
}

{
  "id": "pay_01JY6K6Y8F7P4B2S1Q8Z9R0M3N",
  "status": "approved",
  "amount": "0.03",
  "asset": "USDC",
  "service": "risk-report-api",
  "tx": "5xL...9Qp",
  "policyRevision": "polrev_18",
  "spentToday": "1.45",
  "createdAt": "2026-06-10T09:31:04Z"
}

Field	Type	Description
`agentId`	string	Agent receiving the payment request.
`service`	string	Registered service id, not a raw wallet address.
`amount`	string	Decimal amount in settlement asset units.
`asset`	`USDC \| SOL \| USDT \| PYUSD \| EURC`	Must match the allowance asset. USDC/SOL start first.
`reason`	string	Human-readable purpose shown in logs.
`metadata`	object	Optional app data copied into logs and webhooks.

Send an Idempotency-Key header on payment requests — see Idempotency.

Read budget

GET /v1/agents/:id/budget

Returns current allowance balance, rolling spend, and policy limits.

{
  "agentId": "researchbot-01",
  "status": "active",
  "asset": "USDC",
  "balance": "3.55",
  "spentToday": "1.45",
  "spentThisWeek": "8.12",
  "dailyLimit": "5.00",
  "weeklyLimit": "25.00",
  "maxPerPayment": "0.25",
  "policyRevision": "polrev_18"
}

Field	Type	Description
`status`	`active \| paused`	Current policy-signing state.
`balance`	string	Remaining escrow balance.
`spentToday`	string	Spend in rolling 24h window.
`spentThisWeek`	string	Spend in rolling 7d window.
`policyRevision`	string	Revision used for current limits.

Register a service

POST /v1/services

Creates or updates a service id mapped to a recipient address — see Service registry for the concept.

{
  "id": "risk-report-api",
  "name": "Risk Report API",
  "recipient": "solana:8qZ...F2p",
  "asset": "USDC",
  "webhookUrl": "https://risk.example/webhooks/allowkit"
}

{
  "id": "risk-report-api",
  "name": "Risk Report API",
  "recipient": "solana:8qZ...F2p",
  "asset": "USDC",
  "status": "pending_approval",
  "createdAt": "2026-06-10T09:22:11Z"
}

Errors

Status	Code	Meaning
401	`invalid_api_key`	API key missing, expired, or revoked.
403	`agent_paused`	The agent is paused; all payments fail closed.
403	`service_not_approved`	Service id or recipient address is not approved by policy.
409	`idempotency_conflict`	Same idempotency key was reused with different payload.
422	`budget_exceeded`	Daily, weekly, or max-per-payment limit would be crossed.
503	`policy_signer_unavailable`	AllowKit cannot evaluate/co-sign right now; retry later.