Wallet Policy

List an agent wallet's policy intents (newest first)

get/v1/agent-wallets/{agentWalletId}/policy/intents

Request

  • Base URL: https://api.prod.keyban.io
  • URL: https://api.prod.keyban.io/v1/agent-wallets/{agentWalletId}/policy/intents
  • Auth: one of:
    • API key in header X-Api-Key
    • bearer (a scheme the document does not define)

Path parameters

agentWalletIdstring uuid required

Query parameters

state'pending_human_approval' | 'approved' | 'declined' | 'abandoned' | 'consumed' | 'expired' | 'failed'

Optional state filter (e.g. pending_human_approval for the approval queue)

Response

idstring uuid required

Entity UUID

createdAtstring date-time required

Creation date (ISO 8601)

updatedAtstring date-time required

Last update date (ISO 8601)

hashstring required

Canonical hash of the signing request the intent authorises. 0x-prefixed, 32-byte (64 hex chars). Unique per subject — the same hash is never re-signed (ADR-86 anti-replay).

kindstring required

Payment kind label emitted by the payment extractor (opaque to the engine).

recipientstring required

Case-normalised (lowercased) recipient: an on-chain address for relay payments, or the seller host for x402.

resourcestring nullable

x402 resource the payment unlocks: seller host + path only (query string and fragment stripped, so no per-request secret is stored). Null for relay payments, which target an on-chain address rather than a URL.

assetstring required

Asset symbol/label the amount is denominated in.

amountNativestring required

Raw transfer amount as a decimal integer string, in the asset's smallest unit (wei for ETH, base units for USDC).

amountRefstring required

Reference-currency value at intent creation, as a decimal integer string in centi-units of the policy currency (e.g. 1180 = 11.80).

approvedAmountRefstring nullable

Reference value the human approved — the anchor a later re-validation tolerates volatility drift around (#4254). Null until the first decision.

currentAmountRefstring nullable

Reference value re-priced at read time (#4254), so a human deciding now judges the current worth, not the stale stored one. Present on reads that re-price; absent when not recomputed.

state'pending_human_approval' | 'approved' | 'declined' | 'abandoned' | 'consumed' | 'expired' | 'failed' required

Lifecycle state: pending_human_approval → approved → consumed, or pending_human_approval → declined. Only consumed is terminal; declined is reversible.

decidedAtstring date-time nullable

When a human approved or declined the intent (RFC 3339). Null while still pending.

decidedBystring nullable

Account (email) of the human who approved or declined the intent, captured at decision time. Null for auto-approved intents (no human in the loop) or those still pending.

consumedAtstring date-time nullable

When the signature consumed the intent at /sign (RFC 3339). Null until executed.

expiresAtstring date-time nullable

x402 EIP-3009 validBefore as a wall-clock instant (RFC 3339). Null for relay payments (no time window).

Example response

[
  {
    "hash": "0xa3f1a3f1a3f1a3f1a3f1a3f1a3f1a3f1a3f1a3f1a3f1a3f1a3f1a3f1a3f1a3f1",
    "kind": "usdc-transfer",
    "recipient": "0x4f6e8b129fa2c1b3d5e7a9c0b2d4f6e8a0c2e4f6",
    "resource": "api.shop.example.com/premium/report",
    "asset": "USDC",
    "amountNative": "12500000",
    "amountRef": "1180",
    "approvedAmountRef": "1180",
    "currentAmountRef": "1185",
    "state": "pending_human_approval",
    "decidedAt": "2026-06-17T14:32:00Z",
    "decidedBy": "jane.doe@example.com",
    "consumedAt": "2026-06-17T14:33:10Z",
    "expiresAt": "2026-06-17T14:33:00Z",
    "events": [
      {
        "kind": "human_approved",
        "amountRef": "1180",
        "at": "2026-06-17T14:32:00Z"
      }
    ]
  }
]

Changes

No recorded changes to this operation across all 1 revision of this API.