POST /api/wallets — provision a new agent wallet

Create a scoped wallet for an AI agent. Sets per-transaction and period spend limits, expiry, and optional merchant allowlist. Returns an API key and virtual account.

Provision a new wallet for an AI agent. Each wallet is fully isolated — it carries its own virtual bank account, spend controls, and API key. The agent uses that key to authorise payments; your backend never touches the agent’s funds directly.

Canonical path: POST /api/wallets POST /api/onboarding redirects to this endpoint — use the canonical path for all new integrations.

Endpoint

POST /api/wallets

Authentication

Requires a valid Session JWT in the Authorization header.

Authorization: Bearer <session_jwt>

---

Request Body

name · string · required

Human-readable label for this wallet. Used in the dashboard and transaction receipts. Must be between 1 and 100 characters.

userId · string · required

The ID of the user who owns this wallet, as returned during sign-up. Must be a valid UUID.

spendLimitPerTx · integer · required

Maximum amount the agent may spend in a single transaction, denominated in kobo (100 kobo = ₦1). Requests above this threshold are automatically blocked. Must be a positive integer and must not exceed spendLimitPeriod.

spendLimitPeriod · integer · required

Maximum cumulative spend allowed within the rolling window defined by periodWindowDays, denominated in kobo. Must be greater than or equal to spendLimitPerTx.

periodWindowDays · integer · default: "30" · required

Length of the rolling spend window, in days. The period counter resets on a rolling basis — not calendar-month aligned. Defaults to 30.

expiry · string · required

ISO 8601 datetime at which this wallet should automatically deactivate (e.g. "2026-01-31T23:59:59Z"). Must be a timestamp in the future at the time of the request.

useAllowlist · boolean · default: "false"

When true, the wallet will only approve payments to merchants listed in merchantAllowlist. All other merchants are blocked regardless of spend limits.

merchantAllowlist · string[]

An array of merchant name strings. Required when useAllowlist is true (must contain at least one entry). Merchant names are matched case-insensitively against the name reported by the payment terminal at authorisation time.

["Shopify Store", "AWS", "Vercel"]

---

Cross-field Validation Rules

The following constraints are enforced in addition to individual field validation:

• spendLimitPerTx ≤ spendLimitPeriod — the per-transaction cap cannot exceed the rolling-period cap. A 400 error is returned if this rule is violated.
• merchantAllowlist required when useAllowlist is true — the array must contain at least one merchant name. Omitting it or sending an empty array returns 400.
• expiry must be in the future — the timestamp is validated against the server clock at request time. A past expiry returns 400.

---

Example Request

{
  "name": "Procurement Agent — Q3 2025",
  "userId": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "spendLimitPerTx": 500000,
  "spendLimitPeriod": 2000000,
  "periodWindowDays": 30,
  "expiry": "2027-01-01T00:00:00.000Z",
  "useAllowlist": true,
  "merchantAllowlist": ["AWS", "Vercel", "Stripe"]
}

---

Response 201 Created

The response envelope contains success: true and a data object with three nested objects: wallet, virtualAccount, and apiKey.

success · boolean

Always true for a successful creation.

data · object

Container for the created resources.

Show data fields

data.wallet · object

The newly created wallet object.

Show wallet fields

data.wallet.id · string

Unique wallet UUID. Use this as walletId in all subsequent requests.

data.wallet.name · string

The label supplied at creation time.

data.wallet.userId · string

The owning user’s ID.

data.wallet.businessId · string | null

The associated business ID, or null if not linked to a business account.

data.wallet.balance · integer

Current wallet balance in kobo. Always 0 for a freshly created wallet.

data.wallet.spendLimitPerTx · integer

Per-transaction spend cap, in kobo.

data.wallet.spendLimitPeriod · integer

Rolling-period spend cap, in kobo.

data.wallet.periodWindowDays · integer

Length of the rolling window in days.

data.wallet.useAllowlist · boolean

Whether merchant-allowlist enforcement is active.

data.wallet.merchantAllowlist · string[]

List of permitted merchant names (empty array when useAllowlist is false).

data.wallet.expiry · string

ISO 8601 expiry timestamp as supplied in the request.

data.wallet.expiresAt · string | null

Resolved expiry datetime used internally. May be null until processed.

data.wallet.status · string

Wallet lifecycle status. "ACTIVE" immediately after creation.

data.wallet.apiKeyHash · string | null

Hashed representation of the API key stored server-side. null at creation time — this field is not useful to API consumers and is included for completeness only.

data.wallet.createdAt · string

ISO 8601 timestamp of wallet creation.

data.wallet.updatedAt · string

ISO 8601 timestamp of the most recent update.

data.virtualAccount · object

The virtual bank account automatically provisioned for this wallet.

Show virtualAccount fields

data.virtualAccount.id · string

Virtual account UUID.

data.virtualAccount.walletId · string

The wallet this virtual account is linked to.

data.virtualAccount.accountNumber · string

10-digit Nigerian bank account number assigned to this wallet.

data.virtualAccount.accountName · string

Account name as it appears on bank transfers.

data.virtualAccount.bankName · string

The issuing bank name (e.g. "Providus Bank").

data.virtualAccount.providerRef · string

Provider-assigned reference for this virtual account.

data.virtualAccount.createdAt · string

ISO 8601 timestamp of virtual account creation.

data.apiKey · object

Credentials the agent uses to authorise payments.

Show apiKey fields

data.apiKey.id · string

API key UUID.

data.apiKey.keyPrefix · string

The first several characters of the key — safe to store and display for identification.

data.apiKey.fullKey · string

The complete API key string. See warning below.

data.apiKey.createdAt · string

ISO 8601 timestamp of key creation.

Example Response

{
  "success": true,
  "data": {
    "wallet": {
      "id": "wallet-uuid",
      "name": "Purchasing Agent v1",
      "userId": "user-uuid",
      "businessId": null,
      "balance": 0,
      "spendLimitPerTx": 500000,
      "spendLimitPeriod": 2000000,
      "periodWindowDays": 30,
      "merchantAllowlist": [],
      "useAllowlist": false,
      "expiresAt": null,
      "expiry": "2027-01-01T00:00:00.000Z",
      "status": "ACTIVE",
      "apiKeyHash": null,
      "createdAt": "2026-07-21T09:00:00.000Z",
      "updatedAt": "2026-07-21T09:00:00.000Z"
    },
    "virtualAccount": {
      "id": "va-uuid",
      "walletId": "wallet-uuid",
      "accountNumber": "9876543210",
      "accountName": "Purchasing Agent v1",
      "bankName": "Providus Bank",
      "providerRef": "mock-ref-abc123",
      "createdAt": "2026-07-21T09:00:00.000Z"
    },
    "apiKey": {
      "id": "key-uuid",
      "keyPrefix": "ax_live_9f2a3b",
      "fullKey": "ax_live_9f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2",
      "createdAt": "2026-07-21T09:00:00.000Z"
    }
  }
}

data.apiKey.fullKey is returned exactly once — at creation time. It is never returned again in any subsequent API response. Store it securely (e.g. in a secrets manager or encrypted environment variable) before discarding the response. If the key is lost, you must rotate it via the key-management endpoint.

---

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	One or more request body fields failed validation. Check the errors array in the response body for field-level detail.
400	EXPIRY_IN_PAST	The expiry timestamp is not in the future.
400	ALLOWLIST_REQUIRED	useAllowlist is true but merchantAllowlist is missing or empty.
400	PERIOD_LIMIT_TOO_LOW	spendLimitPeriod is less than spendLimitPerTx.
401	UNAUTHORIZED	Missing or invalid Session JWT.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body validation failed.",
    "errors": [
      {
        "field": "spendLimitPeriod",
        "message": "spendLimitPeriod must be >= spendLimitPerTx"
      }
    ]
  }
}