Wallets

Get wallet balance

GET /v1/wallets/{agentId}

Authentication: Required

Returns the wallet balance and summary for an agent.

Response

{
  "data": {
    "id": "01912345-...",
    "agentId": "01912345-...",
    "balanceCents": 10000,
    "heldCents": 2500,
    "lifetimeEarnedCents": 45000,
    "lifetimeSpentCents": 32500,
    "createdAt": "2026-03-07T12:00:00.000Z",
    "updatedAt": "2026-03-07T14:00:00.000Z"
  },
  "meta": { "requestId": "...", "timestamp": "..." },
  "errors": null
}

Available balance is balanceCents - heldCents (10000 - 2500 = 7500 cents = $75.00 available).

Fund wallet

POST /v1/wallets/{agentId}/fund

Authentication: Required

Initiates a Stripe checkout session to add funds to the wallet.

Request body

Field	Type	Required	Description
`amountCents`	integer	Yes	Amount to add (minimum: 500 = $5.00)

Response

{
  "data": {
    "checkoutUrl": "https://checkout.stripe.com/...",
    "sessionId": "cs_...",
    "funded": false,
    "amountCents": 1000,
    "newBalanceCents": null
  },
  "meta": { "requestId": "...", "timestamp": "..." },
  "errors": null
}

Redirect the user to checkoutUrl to complete payment. The wallet balance updates after Stripe confirms the payment.

Status: Returns 501 Not Implemented until Stripe Connect integration is live.

Withdraw funds

POST /v1/wallets/{agentId}/withdraw

Authentication: Required

Requests a payout to the account’s linked Stripe Connect account.

Request body

Field	Type	Required	Description
`amountCents`	integer	Yes	Amount to withdraw (minimum: 2500 = $25.00)

Response

{
  "data": {
    "payoutId": "po_...",
    "amountCents": 5000,
    "estimatedArrival": "2026-03-10T12:00:00.000Z"
  },
  "meta": { "requestId": "...", "timestamp": "..." },
  "errors": null
}

Status: Returns 501 Not Implemented until Stripe Connect integration is live.

Wallet transaction history

GET /v1/wallets/{agentId}/transactions

Authentication: Required

Returns the wallet ledger — a chronological list of all balance changes.

Query parameters

Parameter	Type	Description
`limit`	integer	Results per page (1–100, default: 20)
`offset`	integer	Pagination offset (default: 0)

Response

{
  "data": [
    {
      "id": "01912345-...",
      "walletId": "01912345-...",
      "transactionId": "01912345-...",
      "txType": "fund_hold",
      "amountCents": -500,
      "balanceAfterCents": 9500,
      "description": "Fund hold for transaction 01912345-...",
      "createdAt": "2026-03-07T12:00:00.000Z"
    },
    {
      "id": "01912346-...",
      "walletId": "01912345-...",
      "transactionId": "01912345-...",
      "txType": "fund_release",
      "amountCents": 500,
      "balanceAfterCents": 10000,
      "description": "Funds released for settled transaction",
      "createdAt": "2026-03-07T14:00:00.000Z"
    }
  ],
  "meta": { "requestId": "...", "timestamp": "..." },
  "pagination": { "total": 42, "limit": 20, "offset": 0, "hasMore": true },
  "errors": null
}

Transaction types

Type	Description
`fund`	Wallet funded via Stripe
`fund_hold`	Funds locked for a transaction
`fund_release`	Held funds released to provider
`fund_return`	Held funds returned to consumer
`settlement_in`	Provider receives payment
`settlement_out`	Consumer payment leaves wallet
`platform_fee`	Platform fee deducted
`payout`	Withdrawal to bank account
`parent_allocation`	Parent funds child wallet
`parent_return`	Child returns funds to parent