The Wallet API allows you to retrieve your current wallet balance and inspect immutable ledger entries representing all financial activity. The wallet is backed by a deterministic, append-only ledger to ensure financial integrity, auditability, and replayability.

Wallet balances are derived from ledger entries and are guaranteed to be consistent.

Wallet Object

Represents the current wallet state.

Field	Type	Description
id	string	Unique wallet identifier
tenantId	string	Unique Tenant identifier
balanceCents	string	Current wallet balance in minor units (Cents in this case)
currency	string	ISO 4217 currency code
created_at	string	ISO 8601 timestamp

Ledger Entry Object

Represents a single immutable financial transaction.

Field	Type	Description
id	string	Unique ledger entry ID
type	string	Entry type (`credit`, `debit`)
amount	string	Transaction amount in minor units
currency	string	ISO currency code
reference	string	External reference identifier
description	string	Human-readable description
balance_after	string	Wallet balance after transaction
created_at	string	ISO 8601 timestamp

Get Wallet Balance

Retrieve the current wallet balance and currency.

curl https://sandbox.travelbase.ai/v1/wallet \
  -H "x-api-key: tb_live_xxxxxxxxxxxxxxxxx"

const response = await fetch(
"https://sandbox.travelbase.ai/v1/wallet",
{
headers: {
"x-api-key": process.env.TRAVELBASE_API_KEY
}
}
);

const wallet = await response.json();
console.log(wallet.balance);

string

Unique identifier for the wallet (prefix: wal_).

balance

string

Current balance. Always returned as a string to prevent floating-point precision issues.

currency

string

ISO 4217 currency code (e.g., USD).

Examples

cURL
JavaScript
Go

curl [https://sandbox.travelbase.ai/v1/wallet](https://sandbox.travelbase.ai/v1/wallet) \
-H "x-api-key: YOUR_API_KEY"

const response = await
fetch("[https://sandbox.travelbase.ai/v1/wallet](https://sandbox.travelbase.ai/v1/wallet)", {
headers: {
"x-api-key": process.env.TRAVELBASE_API_KEY
}
});

const wallet = await response.json();
console.log(`Balance: ${wallet.balance} ${wallet.currency}`);

req, _ := http.NewRequest("GET",
"[https://sandbox.travelbase.ai/v1/wallet](https://sandbox.travelbase.ai/v1/wallet)", nil)
req.Header.Set("x-api-key", apiKey)

client := &http.Client{}
resp, err := client.Do(req)
// ... handle response

Get Wallet Ledger Entries

The ledger endpoint allows you to retrieve a list of immutable ledger entries. Retrieve the 50 most recent ledger entries. Use this for reconciliation and displaying transaction history to users.

This endpoint is rate-limited and returns a maximum of 50 entries per request.

curl https://sandbox.travelbase.ai/v1/wallet/ledger \
  -H "x-api-key: tb_live_xxxxxxxxxxxxxxxxx"

const response = await fetch(
"https://sandbox.travelbase.ai/v1/wallet/ledger",
{
headers: {
"x-api-key": process.env.TRAVELBASE_API_KEY
}
}
);

const ledgerEntries = await response.json();

Response

{
  "data": [
    {
      "id": "led_91ac3f",
      "type": "credit",
      "amount": "50000",
      "currency": "USD",
      "reference": "ord_82hs71",
      "description": "Order payment received",
      "balance_after": "125000",
      "created_at": "2026-02-23T15:01:22Z"
    }
  ]
}

Best Practices

To ensure financial data integrity, we recommend the following: Precision Handling: Never parse balance as a float. Use libraries like Big.js or Decimal.js. Idempotency: Use the reference field (e.g., ord_xxx) to ensure you do not double-process the same transaction in your local database. Webhooks: Don’t poll the ledger endpoint. Subscribe to our ledger.updated webhook for real-time notifications.

Errors

The Travelbase API uses standard HTTP status codes to indicate success or failure.

Error Object

error.statusCode

string

Machine-readable error type.

error.message

string

Human-readable description of the error.

error.code

string

Optional error code for programmatic handling.

Error Codes

HTTP Status	Type	Description
401	authentication_error	Invalid or missing API key
403	forbidden	You do not have permission to access this resource
429	rate_limit_error	Too many requests. Implement exponential backoff
500	internal_server_error	Unexpected server error
503	service_unavailable	Service temporarily unavailable

Example Error Response

{
        "success": false,
        "statusCode": 400,
        "errorCode": "TB_AUTH_101",
        "message": "Invalid API key",
        "fault": "client",
        "retryable": true,
        "suggestedAction": "verify your API key and try again",
        "reason": "Invalid API key",
        "environment": "sandbox",
        "apiVersion": "1.0.0"
    }

Orders

Connect wallet transactions to specific customer orders.

Webhooks

Receive real-time events for wallet debits and credits.

Location

Search

Orders

Financial

Platform

Wallet

Wallet Object

Ledger Entry Object

Get Wallet Balance

Examples

Get Wallet Ledger Entries

Response

Best Practices

Errors

Error Object

Error Codes

Example Error Response

Orders

Webhooks

Location

Search

Orders

Financial

Platform

​Wallet Object

​Ledger Entry Object

​Get Wallet Balance

​Examples

​Get Wallet Ledger Entries

​Response

​Best Practices

​Errors

​Error Object

​Error Codes

​Example Error Response

Orders

Webhooks

Wallet Object

Ledger Entry Object

Get Wallet Balance

Examples

Get Wallet Ledger Entries

Response

Best Practices

Errors

Error Object

Error Codes

Example Error Response