Wallet & Payments

Download Page (.md)

The Wallet & Payments API lets you manage user balances, process payments, issue and download invoices, and maintain payment methods. Use these endpoints to credit general or AI balances, transfer funds between balance types, retrieve fee history, and inspect transaction records for the authenticated user.

Balances

`GET /api/v1/wallet/balances`

Get the user’s aggregate balances, including general balance and AI credit limit, usage, and remaining.

This endpoint takes no parameters.

Response 200

{
  "statusCode": 200,
  "message": "Balances retrieved successfully",
  "data": {
    "general_balance": "125.50",
    "ai_limit": "50.00",
    "ai_usage": "23.45",
    "ai_remaining": "26.55"
  }
}

const balances = await client.api.wallet.getAggregateBalances();

`GET /api/v1/wallet/balances/general`

Get the user’s general balance only.

This endpoint takes no parameters.

Response 200

{
  "statusCode": 200,
  "message": "General balance retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439100",
    "user_id": "507f1f77bcf86cd799439011",
    "general_balance": "125.50",
    "created_at": "2025-01-10T08:30:00.000Z",
    "updated_at": "2025-01-21T20:00:00.000Z"
  }
}

const balance = await client.api.wallet.getGeneralBalance();

`GET /api/v1/wallet/balances/ai`

Get the user’s AI balance — limit, usage, and remaining.

This endpoint takes no parameters.

Response 200

{
  "statusCode": 200,
  "message": "AI balance retrieved successfully",
  "data": {
    "ai_limit": "50.00",
    "ai_usage": "23.45",
    "ai_remaining": "26.55"
  }
}

const aiBalance = await client.api.wallet.getAiBalance();

Transfers

`POST /api/v1/wallet/transfers`

One-way transfer from the general balance to the AI credit balance. The amount must be a strict string in USD with up to 2 decimals.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`amount`	string	Yes	USD amount as a string with up to 2 decimals, e.g. `"10.00"`. No exponent, no negatives.

{
  "amount": "25.00"
}

Response 200

{
  "statusCode": 200,
  "message": "Transfer completed and AI credit limit synced",
  "data": {
    "gross_transferred": "25.00",
    "net_ai_credit": "23.75",
    "fee": "1.25",
    "general_balance": "100.50",
    "ai_balance": "75.00",
    "key_created": false
  }
}

const result = await client.api.wallet.transferToAi({
  amount: "25.00"
});

AI Fee History

`GET /api/v1/wallet/ai-fee-history`

Paginated list of platform fees charged on AI credit transfers and admin credits.

Parameters

Name	In	Type	Required	Description
`page`	query	number	No	Page number. Default: `1`.
`limit`	query	number	No	Items per page. Default: `20`.
`sort_by`	query	string	No	Field to sort by. Allowed: `"created_at"`, `"amount"`, `"transaction_id"`. Default: `"created_at"`.
`sort_order`	query	string	No	Sort direction. Allowed: `"asc"`, `"desc"`. Default: `"desc"`.

Response 200

{
  "statusCode": 200,
  "message": "AI fee history retrieved successfully",
  "data": {
    "fees": [
      {
        "id": "507f1f77bcf86cd799439150",
        "transaction_id": "507f1f77bcf86cd799439140",
        "amount": "1.25",
        "created_at": "2025-01-21T20:00:00.000Z",
        "transaction": {
          "id": "507f1f77bcf86cd799439140",
          "reason": "Transfer to AI credits",
          "amount": "25.00"
        }
      }
    ],
    "pagination": {
      "total": 12,
      "page": 1,
      "limit": 20,
      "totalPages": 1
    }
  }
}

const fees = await client.api.wallet.listAiFeeHistoryIterator({
  page: 1,
  limit: 20
});

Transactions

`GET /api/v1/wallet/transactions`

List wallet transactions for the authenticated user.

Parameters

Name	In	Type	Required	Description
`limit`	query	number	No	Items per page. Default: `20`.
`sort_by`	query	string	No	Field to sort by. Allowed: `"id"`, `"transaction_type"`, `"status"`, `"amount"`, `"created_at"`, `"updated_at"`. Default: `"created_at"`.
`sort_order`	query	string	No	Sort direction. Allowed: `"asc"`, `"desc"`. Default: `"desc"`.

Response 200

{
  "statusCode": 200,
  "message": "Transactions retrieved successfully",
  "data": {
    "transactions": [],
    "pagination": {
      "total": 0,
      "page": 1,
      "limit": 20,
      "totalPages": 0
    }
  }
}

const transactions = await client.api.wallet.listTransactionsIterator({
  limit: 20
});

`GET /api/v1/wallet/transactions/{id}`

Get a single transaction by ID.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Transaction ID.

Response 200

{
  "statusCode": 200,
  "message": "Transaction retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439140"
  }
}

const transaction = await client.api.wallet.getTransaction({
  id: "507f1f77bcf86cd799439140"
});

Invoices

`GET /api/v1/wallet/invoices/`

List all invoices for the authenticated user.

Parameters

Name	In	Type	Required	Description
`limit`	query	number	No	Items per page. Default: `20`.
`sort_by`	query	string	No	Field to sort by. Default: `"created_at"`.
`sort_order`	query	string	No	Sort direction. Allowed: `"asc"`, `"desc"`. Default: `"desc"`.

Response 200

{
  "statusCode": 200,
  "message": "Invoices retrieved successfully",
  "data": {
    "invoices": [
      {
        "id": "507f1f77bcf86cd799439120",
        "user_id": "507f1f77bcf86cd799439011",
        "transaction_id": "507f1f77bcf86cd799439110",
        "invoice_number": "INV-2025-000456",
        "status": "paid",
        "amount": 50,
        "currency": "USD",
        "issue_date": "2025-01-20T15:30:00.000Z",
        "due_date": "2025-02-20T15:30:00.000Z",
        "paid_date": "2025-01-20T15:30:00.000Z",
        "created_at": "2025-01-20T15:30:00.000Z",
        "updated_at": "2025-01-20T15:30:00.000Z",
        "transaction": {
          "id": "507f1f77bcf86cd799439110",
          "transaction_type": "payment",
          "status": "completed",
          "amount": 50,
          "currency": "USD",
          "created_at": "2025-01-20T15:30:00.000Z"
        }
      }
    ],
    "pagination": {
      "total": 23,
      "page": 1,
      "limit": 10,
      "totalPages": 3
    }
  }
}

const invoices = await client.api.wallet.listInvoicesIterator({
  limit: 20
});

`GET /api/v1/wallet/invoices/{id}`

Get a specific invoice by ID.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Invoice ID.

Response 200
Response 404

{
  "statusCode": 200,
  "message": "Invoice retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439120",
    "user_id": "507f1f77bcf86cd799439011",
    "transaction_id": "507f1f77bcf86cd799439110",
    "invoice_number": "INV-2025-000456",
    "status": "paid",
    "amount": 50,
    "currency": "USD",
    "billing_details": {
      "name": "John Doe",
      "address": "123 Main St"
    },
    "items": [
      {
        "description": "Account credit",
        "amount": 50
      }
    ],
    "issue_date": "2025-01-20T15:30:00.000Z",
    "due_date": "2025-02-20T15:30:00.000Z",
    "paid_date": "2025-01-20T15:30:00.000Z",
    "created_at": "2025-01-20T15:30:00.000Z",
    "updated_at": "2025-01-20T15:30:00.000Z",
    "transaction": {
      "id": "507f1f77bcf86cd799439110",
      "transaction_type": "payment",
      "status": "completed",
      "amount": 50,
      "currency": "USD",
      "created_at": "2025-01-20T15:30:00.000Z"
    }
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Invoice not found"
}

const invoice = await client.api.wallet.getInvoice({
  id: "507f1f77bcf86cd799439120"
});

`GET /api/v1/wallet/invoices/{id}/pdf`

Download an invoice as a PDF.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Invoice ID.

Response 200
Response 404

Returns a binary PDF file with Content-Type: application/pdf.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Invoice not found"
}

const pdf = await client.api.wallet.downloadInvoicePdf({
  id: "507f1f77bcf86cd799439120"
});

`POST /api/v1/wallet/invoices/generate/{id}`

Generate an invoice for a specific transaction. Returns 200 with the existing invoice if one is already associated, or 201 when a new invoice is created.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Transaction ID.

{
  "statusCode": 200,
  "message": "Invoice already exists",
  "data": {
    "invoice_id": "507f1f77bcf86cd799439120",
    "invoice_number": "INV-2025-000456"
  }
}

{
  "statusCode": 201,
  "message": "Invoice generated successfully",
  "data": {
    "invoice_id": "507f1f77bcf86cd799439121",
    "invoice_number": "INV-2025-000457"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Transaction not found"
}

const result = await client.api.wallet.generateInvoice({
  id: "507f1f77bcf86cd799439110"
});

Payment Methods

`GET /api/v1/wallet/payment-methods/`

List all payment methods for the authenticated user.

This endpoint takes no parameters.

Response 200

{
  "statusCode": 200,
  "message": "Payment methods retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439130",
      "user_id": "507f1f77bcf86cd799439011",
      "type": "credit_card",
      "name": "Visa ending in 4242",
      "status": "active",
      "details": {
        "last4": "4242",
        "brand": "visa",
        "exp_month": 12,
        "exp_year": 2026
      },
      "is_default": true,
      "created_at": "2025-01-15T10:00:00.000Z",
      "updated_at": "2025-01-15T10:00:00.000Z"
    }
  ]
}

const methods = await client.api.wallet.listPaymentMethodsIterator();

`GET /api/v1/wallet/payment-methods/{id}`

Get a single payment method by ID.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Payment method ID.

Response 200
Response 404

{
  "statusCode": 200,
  "message": "Payment method retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439130",
    "user_id": "507f1f77bcf86cd799439011",
    "type": "credit_card",
    "name": "Visa ending in 4242",
    "status": "active",
    "details": {
      "last4": "4242",
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2026
    },
    "is_default": true,
    "created_at": "2025-01-15T10:00:00.000Z",
    "updated_at": "2025-01-15T10:00:00.000Z"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment method not found"
}

const method = await client.api.wallet.getPaymentMethod({
  id: "507f1f77bcf86cd799439130"
});

`POST /api/v1/wallet/payment-methods/`

Add a new payment method for the authenticated user.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`type`	string	Yes	Payment method type (e.g. `credit_card`).
`name`	string	Yes	Display name for the payment method.
`details`	object	No	Provider-specific details (e.g. last4, brand, expiry).
`is_default`	boolean	No	Whether to mark this method as the default.

{
  "type": "credit_card",
  "name": "Mastercard ending in 5555",
  "details": {
    "last4": "5555",
    "brand": "mastercard",
    "exp_month": 8,
    "exp_year": 2027
  },
  "is_default": false
}

Response 201
Response 400

{
  "statusCode": 201,
  "message": "Payment method added successfully",
  "data": {
    "id": "507f1f77bcf86cd799439131",
    "user_id": "507f1f77bcf86cd799439011",
    "type": "credit_card",
    "name": "Mastercard ending in 5555",
    "status": "active",
    "details": {
      "last4": "5555",
      "brand": "mastercard",
      "exp_month": 8,
      "exp_year": 2027
    },
    "is_default": false,
    "created_at": "2025-01-21T20:30:00.000Z",
    "updated_at": "2025-01-21T20:30:00.000Z"
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid payment method payload"
}

const method = await client.api.wallet.addPaymentMethod({
  type: "credit_card",
  name: "Mastercard ending in 5555",
  details: {
    last4: "5555",
    brand: "mastercard",
    exp_month: 8,
    exp_year: 2027
  },
  is_default: false
});

`PATCH /api/v1/wallet/payment-methods/{id}`

Update an existing payment method. Any of details, status, or is_default may be sent.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Payment method ID.

Request Body

Name	Type	Required	Description
`details`	object	No	Updated provider-specific details.
`status`	string	No	New status. Allowed: `"active"`, `"inactive"`.
`is_default`	boolean	No	Whether this method should be the default.

{
  "status": "active",
  "is_default": true
}

Response 200
Response 404

{
  "statusCode": 200,
  "message": "Payment method updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439131",
    "user_id": "507f1f77bcf86cd799439011",
    "type": "credit_card",
    "name": "Mastercard (primary)",
    "status": "active",
    "details": {
      "last4": "5555",
      "brand": "mastercard",
      "exp_month": 10,
      "exp_year": 2027
    },
    "is_default": true,
    "created_at": "2025-01-21T20:30:00.000Z",
    "updated_at": "2025-01-21T20:45:00.000Z"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment method not found"
}

const updated = await client.api.wallet.updatePaymentMethod({
  id: "507f1f77bcf86cd799439131",
  status: "active",
  is_default: true
});

`PATCH /api/v1/wallet/payment-methods/{id}/default`

Mark an existing payment method as the default.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Payment method ID.

Response 200
Response 404

{
  "statusCode": 200,
  "message": "Default payment method set successfully",
  "data": {
    "id": "507f1f77bcf86cd799439131",
    "user_id": "507f1f77bcf86cd799439011",
    "type": "credit_card",
    "name": "Mastercard (primary)",
    "status": "active",
    "details": {
      "last4": "5555",
      "brand": "mastercard",
      "exp_month": 10,
      "exp_year": 2027
    },
    "is_default": true,
    "created_at": "2025-01-21T20:30:00.000Z",
    "updated_at": "2025-01-21T21:00:00.000Z"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment method not found"
}

const result = await client.api.wallet.setDefaultPaymentMethod({
  id: "507f1f77bcf86cd799439131"
});

`DELETE /api/v1/wallet/payment-methods/{id}`

Delete an existing payment method.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Payment method ID.

Response 200
Response 404

{
  "statusCode": 200,
  "message": "Payment method deleted successfully"
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment method not found"
}

await client.api.wallet.deletePaymentMethod({
  id: "507f1f77bcf86cd799439131"
});

Payments

`POST /api/v1/wallet/payments/`

Process a payment using a specified payment method. The amount is a strict string in USD with up to 2 decimals.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`payment_method_id`	string	Yes	ID of the payment method to charge.
`amount`	string	Yes	USD amount as a strict string with up to 2 decimals (e.g. `"10"`, `"10.00"`). No negatives, no exponent.
`credit_distribution`	array	No	Optional; currently informational. If provided, amounts must be strict dollar strings.
`reason`	string	No	Free-form reason or memo for the payment.

{
  "payment_method_id": "507f1f77bcf86cd799439130",
  "amount": "100.00",
  "reason": "Monthly subscription payment"
}

{
  "statusCode": 200,
  "message": "Payment processed successfully",
  "data": {
    "transaction": {
      "id": "507f1f77bcf86cd799439140",
      "user_id": "507f1f77bcf86cd799439011",
      "payment_method_id": "507f1f77bcf86cd799439130",
      "transaction_type": "payment",
      "status": "completed",
      "amount": 100,
      "currency": "USD",
      "gateway_name": "stripe",
      "gateway_transaction_id": "ch_3ABC123xyz",
      "reason": "Monthly subscription payment",
      "created_at": "2025-01-21T20:00:00.000Z",
      "updated_at": "2025-01-21T20:00:00.000Z"
    },
    "invoice": {
      "id": "507f1f77bcf86cd799439141",
      "invoice_number": "INV-2025-000789"
    },
    "balance": {
      "id": "507f1f77bcf86cd799439100",
      "user_id": "507f1f77bcf86cd799439011",
      "balance": 225.5,
      "created_at": "2025-01-10T08:30:00.000Z",
      "updated_at": "2025-01-21T20:00:00.000Z"
    }
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid payment request"
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment method not found"
}

const result = await client.api.wallet.processPayment({
  payment_method_id: "507f1f77bcf86cd799439130",
  amount: "100.00",
  reason: "Monthly subscription payment"
});

`GET /api/v1/wallet/payments/{id}`

Get the status of a payment by ID.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Payment ID.

Response 200
Response 404

{
  "statusCode": 200,
  "message": "Payment status retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439140",
    "user_id": "507f1f77bcf86cd799439011",
    "payment_method_id": "507f1f77bcf86cd799439130",
    "transaction_type": "payment",
    "status": "completed",
    "amount": 100,
    "currency": "USD",
    "gateway_name": "stripe",
    "gateway_transaction_id": "ch_3ABC123xyz",
    "reason": "Monthly subscription payment",
    "created_at": "2025-01-21T20:00:00.000Z",
    "updated_at": "2025-01-21T20:00:00.000Z",
    "details": [
      {
        "id": "507f1f77bcf86cd799439142",
        "transaction_id": "507f1f77bcf86cd799439140",
        "credit_type": "general",
        "amount": 100,
        "created_at": "2025-01-21T20:00:00.000Z"
      }
    ],
    "invoice": {
      "id": "507f1f77bcf86cd799439141",
      "invoice_number": "INV-2025-000789",
      "status": "paid",
      "issue_date": "2025-01-21T20:00:00.000Z",
      "paid_date": "2025-01-21T20:00:00.000Z"
    }
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment not found"
}

const status = await client.api.wallet.getPaymentStatus({
  id: "507f1f77bcf86cd799439140"
});