Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.travelbase.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.
FieldTypeDescription
idstringUnique wallet identifier
tenantIdstringUnique Tenant identifier
balanceCentsstringCurrent wallet balance in minor units (Cents in this case)
currencystringISO 4217 currency code
created_atstringISO 8601 timestamp

​
Ledger Entry Object

Represents a single immutable financial transaction.
FieldTypeDescription
idstringUnique ledger entry ID
typestringEntry type (credit, debit)
amountstringTransaction amount in minor units
currencystringISO currency code
referencestringExternal reference identifier
descriptionstringHuman-readable description
balance_afterstringWallet balance after transaction
created_atstringISO 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);
​
id
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 [https://sandbox.travelbase.ai/v1/wallet](https://sandbox.travelbase.ai/v1/wallet) \
-H "x-api-key: YOUR_API_KEY"

​
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 StatusTypeDescription
401authentication_errorInvalid or missing API key
403forbiddenYou do not have permission to access this resource
429rate_limit_errorToo many requests. Implement exponential backoff
500internal_server_errorUnexpected server error
503service_unavailableService 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.