> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.cacolombia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# In-Game Economy and Wallets in CA Colombia

> Each approved character has a wallet tracking their balance. Learn how the economy works, wallet fields, and how to read and update balances.

CA Colombia features a simulated economy where every approved character holds a **wallet** that tracks their in-game financial balance. The economy powers transactions between characters, salary payouts, business income, fines, and purchases — all flowing through wallet and bank account balances. Understanding how wallets work is essential for building integrations that read or modify a character's financial state.

## The Wallet Object

A wallet is automatically created the first time an approved character's wallet endpoint is accessed. It belongs exclusively to one character and cannot be transferred or shared.

| Field         | Type                 | Description                          |
| ------------- | -------------------- | ------------------------------------ |
| `characterId` | `string` (Snowflake) | The character this wallet belongs to |
| `balance`     | `number`             | The character's current balance      |
| `createdAt`   | `string` (ISO 8601)  | When the wallet was created          |
| `updatedAt`   | `string` (ISO 8601)  | When the wallet was last modified    |

<Note>
  A wallet is only available for characters with `idStatus: "approved"`. Attempting to access wallet endpoints for a `draft` or `pending_approval` character returns `403 Unauthorized`.
</Note>

***

## Wallet Lifecycle

<Steps>
  <Step title="Character is approved">
    Staff approve the character submission. The character's `idStatus` becomes `"approved"` and it becomes eligible for a wallet.
  </Step>

  <Step title="Wallet is created on first access">
    The wallet is provisioned lazily — it is created the first time you call `GET /v1/users/{userId}/characters/{characterId}/wallet` for an approved character that does not yet have one. You do not need to explicitly create it.
  </Step>

  <Step title="Balance updates through transactions">
    Administrators can update balances directly via `PATCH` (set a specific balance value) or `PUT` (apply a transaction amount). Regular users read their own balance using `GET`.
  </Step>
</Steps>

***

## Reading a Wallet

Any authenticated user can read their own character's wallet. Staff members can read wallets for any character.

```http theme={null}
GET /v1/users/{userId}/characters/{characterId}/wallet
```

**Example response:**

```json theme={null}
{
  "characterId": "9876543210987654321",
  "balance": 15000,
  "createdAt": "2024-03-10T09:20:00.000Z",
  "updatedAt": "2024-06-01T14:30:00.000Z"
}
```

***

## Updating a Wallet

Wallet write operations require the `ADMINISTRATOR` permission. Two update modes are available depending on what you need to do:

<CardGroup cols={2}>
  <Card title="PATCH — Set Balance" icon="pen-to-square">
    Sets the wallet balance to an exact value. Use this when you want to assign a precise balance, such as resetting a character's funds or correcting an error.

    ```http theme={null}
    PATCH /v1/users/{userId}/characters/{characterId}/wallet
    ```

    **Body:**

    ```json theme={null}
    { "balance": 25000 }
    ```
  </Card>

  <Card title="PUT — Apply Transaction" icon="arrow-right-arrow-left">
    Applies a transaction by adding or subtracting an `amount` from the current balance. Use positive values to credit funds and negative values to debit. The server records a transaction history entry.

    ```http theme={null}
    PUT /v1/users/{userId}/characters/{characterId}/wallet
    ```

    **Body:**

    ```json theme={null}
    { "amount": -5000 }
    ```
  </Card>
</CardGroup>

<Warning>
  Both `PATCH` and `PUT` require the `ADMINISTRATOR` permission. Standard users (`USER`) can only read their wallet balance — they cannot modify it directly through the API.
</Warning>

***

## Bank Accounts

In addition to their wallet balance, approved characters can hold accounts at in-game banks. Bank accounts provide another layer to the economy, allowing characters to deposit and save funds separately from their on-hand balance.

To retrieve all bank accounts linked to a character:

```http theme={null}
GET /v1/users/{userId}/characters/{characterId}/bankAccounts
```

**Example response:**

```json theme={null}
{
  "bankAccounts": [
    {
      "accountId": "1111222233334444555",
      "bankId": "6666777788889999000",
      "characterId": "9876543210987654321",
      "balance": 50000,
      "createdAt": "2024-04-01T08:00:00.000Z",
      "updatedAt": "2024-05-15T16:45:00.000Z"
    }
  ]
}
```

<Note>
  Like wallets, bank account endpoints are only accessible for `approved` characters. A `403` error is returned for characters in any other status.
</Note>

Bank accounts are created through the banking API. Each bank account is scoped to a specific bank and character pair — a character can hold at most one account per bank. See the Banking section of the API Reference for full details on creating and managing bank accounts.

***

## Economy at a Glance

| Operation            | Endpoint                                                       | Required Permission               |
| -------------------- | -------------------------------------------------------------- | --------------------------------- |
| Read wallet          | `GET /v1/users/{userId}/characters/{characterId}/wallet`       | `USER` (own character) or `STAFF` |
| Set balance directly | `PATCH /v1/users/{userId}/characters/{characterId}/wallet`     | `ADMINISTRATOR`                   |
| Apply a transaction  | `PUT /v1/users/{userId}/characters/{characterId}/wallet`       | `ADMINISTRATOR`                   |
| List bank accounts   | `GET /v1/users/{userId}/characters/{characterId}/bankAccounts` | `USER` (own character) or `STAFF` |