---
title: "Create an agent wallet"
method: POST
path: "/v1/agent-wallets"
tags: ["Agent Wallets"]
---

# Create an agent wallet

`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)

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

## Request body

- CreateAgentWalletDto
  - `application` string, uuid, required: Application ID
  - `label` string, 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.
  - `owner` string, 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.
  - `policy` object: Optional spending policy persisted atomically with the wallet. When provided, the wallet, its first signer and this policy are committed in a single transaction, so a deployed wallet can never be left without its spending caps. Omit to create a wallet with no policy (caps can be set later via PUT .../policy).
    - `currency` string, required: Reference currency the caps are denominated in, as an ISO 4217 code (e.g. EUR, USD, JPY). Any code the rate oracle can quote works — no enum.
    - `maxAmountPerPaymentRef` string, nullable: Per-signature ceiling, expressed as a non-negative integer in the smallest sub-unit of the policy reference currency. Null = no cap.
    - `requireHumanAboveRef` string, nullable: Threshold (same encoding as maxAmountPerPaymentRef) above which evaluateIntent returns require_human. Null = never require human approval.
    - `volatilityMarginBps` integer, nullable: Volatility tolerance in basis points (100 = 1%, max 10000 = 100%) applied when re-validating an already-approved intent against a freshly re-priced amount. Absorbs rate drift between the human approval and the signature: a retry is honored while the value stays within this margin of the approved value, otherwise it is re-escalated for a fresh human decision. Null/0 = strict (no tolerance).
    - `timezone` string, nullable: IANA time zone the budget windows are computed in (e.g. Europe/Paris). Null = UTC.
    - `maxAmountPerDayRef` string, nullable: Spend envelope over the current calendar day (in the policy timezone). Same encoding as maxAmountPerPaymentRef. Null = no daily envelope.
    - `maxAmountPerWeekRef` string, nullable: Spend envelope over the current calendar week (Monday→Sunday, in the policy timezone). Same encoding as maxAmountPerPaymentRef. Null = no weekly envelope.
    - `maxAmountPerMonthRef` string, nullable: Spend envelope over the current calendar month (in the policy timezone). Same encoding as maxAmountPerPaymentRef. Null = no monthly envelope.

## Response `201`

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.

- AgentWalletDtoOutput
  - `id` string, uuid, required: Entity UUID
  - `createdAt` string, date-time, required: Creation date (ISO 8601)
  - `updatedAt` string, date-time, required: Last update date (ISO 8601)
  - `label` string, required: Human-readable label for the wallet
  - `applicationId` string, uuid, required: Application this wallet belongs to
  - `address` string, 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.
  - `owner` object, nullable, required: Owner (responsable) accountable for the wallet spending. Null on wallets created before owners were introduced.
    - `id` string, uuid, required: User ID of the owner.
    - `name` string, required: Display name of the owner, as set on their user profile.
    - `email` string, email, required: Email address of the owner.
  - `whitelist` string[], 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.
  - `budget` object, nullable, required: Per-window (day/week/month) spending budget usage derived from the wallet's policy: each window carries its cap and the amount already consumed. Null when the wallet has no policy. Surfaced here so the admin can show budget consumption without extra calls.
    - `currency` string, required: ISO 4217 code the caps and spent amounts are denominated in.
    - `day` object, required: Calendar-day window (policy timezone).
      - `cap` string, nullable, required: Spending cap for the window, in reference-currency sub-units (e.g. EUR cents — divide by 100 for the major amount). Null = no cap.
      - `spent` string, required: Amount already consumed in the window, same sub-unit encoding as `cap`. Sum of the reference amounts of consumed policy intents since the window start. "0" when nothing was spent.
    - `week` object, required: Calendar-week window, Monday→Sunday (policy timezone).
      - `cap` string, nullable, required: Spending cap for the window, in reference-currency sub-units (e.g. EUR cents — divide by 100 for the major amount). Null = no cap.
      - `spent` string, required: Amount already consumed in the window, same sub-unit encoding as `cap`. Sum of the reference amounts of consumed policy intents since the window start. "0" when nothing was spent.
    - `month` object, required: Calendar-month window (policy timezone).
      - `cap` string, nullable, required: Spending cap for the window, in reference-currency sub-units (e.g. EUR cents — divide by 100 for the major amount). Null = no cap.
      - `spent` string, required: Amount already consumed in the window, same sub-unit encoding as `cap`. Sum of the reference amounts of consumed policy intents since the window start. "0" when nothing was spent.
  - `emergencyStop` boolean, 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.

## Other responses

- `422`: Owner is not a member of the organization

---

[API](https://skmtc.dev/keyban/apis/keyban-rest-apis.md) · [All operations](https://skmtc.dev/keyban/apis/keyban-rest-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/keyban/apis/keyban-rest-apis/revisions/0bb79a1da961?raw)