Wallet

Manage workspace wallet balance and transaction history. Credits are added via Checkout.

Auth: Session token or platform key with X-Workspace-Id header.

Check Balance

GET /v1/platform/wallet/balance

Returns the current workspace wallet balance.

No parameters.

const balance = await billing.wallet.getBalance()

Response

{
  "currency": "USD",
  "amount": "142.350000"
}

Field	Type	Required	Description
`currency`	string	Always	Currency code (`USD`)
`amount`	string	Always	Current balance in USD

List Transactions

GET /v1/platform/wallet/transactions

Returns transaction history for the workspace wallet, ordered by created_at DESC, id DESC. The operator endpoint GET /v1/platform/customers/:workspace_id/transactions accepts the same query parameters and returns the same response shape.

Query Parameters

Name	Type	Required	Description
`limit`	number	No	Results per page. Default: 50, maximum: 100
`offset`	number	No	Number of results to skip. Default: 0. Cannot be combined with `cursor`
`cursor`	string	No	Opaque `next_cursor` from the previous page. Cannot be combined with `offset`
`type`	string	No	Comma-separated list of `credit`, `debit`, `refund`, `adjustment` to include
`exclude_type`	string	No	Comma-separated list of those transaction types to exclude

const { data, next_cursor } = await billing.wallet.getTransactions({
  limit: 10,
  type: ['credit', 'refund'],
})
const nextPage = next_cursor
  ? await billing.wallet.getTransactions({ limit: 10, type: ['credit', 'refund'], cursor: next_cursor })
  : null

Response

{
  "data": [
    {
      "id": "txn_a1b2c3d4",
      "type": "debit",
      "amount_usd": "-0.003420",
      "balance_after": "142.346580",
      "description": "gpt-4o — 150 tokens",
      "reference_type": "api_request",
      "created_at": "2025-01-15T12:30:00.000Z"
    }
  ],
  "next_cursor": null
}

Field	Type	Required	Description
`id`	string	Always	Transaction ID
`type`	string	Always	`credit`, `debit`, `refund`, or `adjustment`
`amount_usd`	string	Always	Signed amount (negative for debits)
`balance_after`	string	Always	Balance after this transaction
`description`	string	Always	Human-readable description
`reference_type`	string	Always	`api_request`, `stripe_checkout`, or `manual`
`created_at`	string	Always	ISO 8601 timestamp

next_cursor is always present. Pass it as cursor to read the next page. null means there are no more results. Keep the same filters when paging.

Create Checkout

POST /v1/platform/wallet/checkout

Create a Stripe checkout session for topping up the wallet. Redirects the user to Stripe.

Body Parameters

Name	Type	Required	Description
`amount`	number	Yes	Top-up amount in USD
`success_url`	string	Yes	Redirect URL after successful payment
`cancel_url`	string	Yes	Redirect URL if user cancels
`workspace_id`	string	No	Override workspace (platform key only)

const checkout = await billing.checkout.create({
  amount: 50,
  successUrl: 'https://app.example.com/billing?status=success',
  cancelUrl: 'https://app.example.com/billing?status=cancelled',
})
// Redirect user to checkout.url

Response

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "base_amount": "50.000000",
  "platform_fee": "2.500000",
  "markup": "5.000000",
  "total_amount": "57.500000"
}

Field	Type	Required	Description
`url`	string	Always	Stripe checkout URL -- redirect the user here
`base_amount`	string	Always	The requested top-up amount
`platform_fee`	string	Always	Fee charged by Assistant Billing
`markup`	string	Always	Operator markup
`total_amount`	string	Always	Total charged to customer