Agent Wallets

Create an agent wallet

Create a new agent wallet for an application in the current organization.

post/v1/agent-wallets

Request

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

Request body

applicationstring uuid required

Application ID

labelstring required

Human-readable label for the wallet

network'EthereumAnvil' | 'BaseSepolia' | 'BaseMainnet' | 'XdcApothem' | 'XdcMainnet' | 'StellarQuickstart' | 'StellarTestnet' | 'StellarMainnet' required

Blockchain network for the wallet

paymentRail'x402'

Settlement rail the wallet uses to move funds. Defaults to x402 (USDC over the x402 protocol), the only rail wired today.

ownerstring uuid

User ID of the owner (responsable) accountable for this wallet. Must be a member of the organization owning the application. Defaults to the authenticated session user when omitted.

Example request

{
  "paymentRail": "x402",
  "owner": "550e8400-e29b-41d4-a716-446655440000"
}

Response

Agent wallet created successfully. The first signer is provisioned by the deploy consumer; once it transitions to "ready", its apiKey and invitation secret are available via GET /agent-wallets/:id/signers.

idstring uuid required

Entity UUID

createdAtstring date-time required

Creation date (ISO 8601)

updatedAtstring date-time required

Last update date (ISO 8601)

labelstring required

Human-readable label for the wallet

applicationIdstring uuid required

Application this wallet belongs to

addressstring required

On-chain address of the wallet

status'deploying' | 'ready' | 'active' | 'failed' required

Current deployment status of the wallet

network'EthereumAnvil' | 'BaseSepolia' | 'BaseMainnet' | 'XdcApothem' | 'XdcMainnet' | 'StellarQuickstart' | 'StellarTestnet' | 'StellarMainnet' required

Blockchain network of the wallet

paymentRail'x402' required

Settlement rail the wallet uses to move funds.

whiteliststring[] required

Bare x402 domains this wallet may pay on — the domains of its wallet-scope destination allow rule. Empty when the wallet has no allow rule (a deny-list or no rule leaves it empty). Surfaced here so the admin list can render the domains without a second call.

emergencyStopboolean required

True while the wallet is paused by its emergency stop: every payment is refused until it is resumed. False when the wallet has no policy.

Example response

{
  "paymentRail": "x402",
  "owner": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Jeanne Martin",
    "email": "jeanne.martin@example.com"
  },
  "whitelist": [
    "api.example.com",
    "openai.com"
  ],
  "budget": {
    "currency": "EUR",
    "day": {
      "cap": "50000",
      "spent": "12500"
    },
    "week": {
      "cap": "50000",
      "spent": "12500"
    },
    "month": {
      "cap": "50000",
      "spent": "12500"
    }
  }
}

Changes

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