> ## 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.

# Wallet

> Retrieve wallet balance and view immutable ledger entries.

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.

<Note>
  Wallet balances are derived from ledger entries and are guaranteed to be consistent.
</Note>

***

## 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.

```bash theme={null}
curl https://sandbox.travelbase.ai/v1/wallet \
  -H "x-api-key: tb_live_xxxxxxxxxxxxxxxxx"
```

```javascript theme={null}
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);
```

<ResponseField name="id" type="string">
  Unique identifier for the wallet (prefix: wal\_).
</ResponseField>

<ResponseField name="balance" type="string">
  Current balance. Always returned as a string to prevent floating-point precision issues.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code (e.g., USD).
</ResponseField>

# Examples

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl [https://sandbox.travelbase.ai/v1/wallet](https://sandbox.travelbase.ai/v1/wallet) \
    -H "x-api-key: YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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}`);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    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
    ```
  </Tab>
</Tabs>

# 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.

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

```bash theme={null}
curl https://sandbox.travelbase.ai/v1/wallet/ledger \
  -H "x-api-key: tb_live_xxxxxxxxxxxxxxxxx"
```

```javascript theme={null}
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

```json theme={null}
{
  "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

<ResponseField name="error.statusCode" type="string">
  Machine-readable error type.
</ResponseField>

<ResponseField name="error.message" type="string">
  Human-readable description of the error.
</ResponseField>

<ResponseField name="error.code" type="string">
  Optional error code for programmatic handling.
</ResponseField>

***

## 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

```json theme={null}

{
        "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"
    }

```

<CardGroup cols={2}>
  <Card title="Orders" icon="receipt" href="/tenant-api/orders">
    Connect wallet transactions to specific customer orders.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/tenant-api/webhooks">
    Receive real-time events for wallet debits and credits.
  </Card>
</CardGroup>