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

# PATCH/PUT /v1/users/:userId/characters/:characterId/wallet

> Update a character's in-game wallet. PATCH sets an exact absolute balance; PUT applies a signed transaction delta to the current balance. Both require ADMINISTRATOR.

The wallet endpoints let administrators adjust a character's in-game currency balance. There are two distinct operations depending on the HTTP method you use:

* **`PATCH`** — Sets the wallet's `balance` field to an exact absolute value you specify. Use this to correct or override a balance directly.
* **`PUT`** — Applies a transaction by adding (or subtracting) an `amount` to the current balance. Use this for incremental adjustments such as paying out rewards or deducting fines.

Both operations require the `ADMINISTRATOR` permission. If the character does not yet have a wallet, `PATCH` creates one before applying the update.

<Warning>
  Both `PATCH` and `PUT` require the `ADMINISTRATOR` permission. Regular users cannot call these endpoints.
</Warning>

<Note>
  Both endpoints only work on characters with an `idStatus` of `approved`. Attempting to update the wallet of an unapproved character returns `403`.
</Note>

## Endpoint

```text theme={null}
PATCH https://api.cacolombia.com/v1/users/:userId/characters/:characterId/wallet
PUT   https://api.cacolombia.com/v1/users/:userId/characters/:characterId/wallet
```

## Path Parameters

<ParamField path="userId" type="string" required>
  The Snowflake ID of the user account that owns the character.
</ParamField>

<ParamField path="characterId" type="string" required>
  The Snowflake ID of the character whose wallet you want to update.
</ParamField>

## Request Body — PATCH

<ParamField body="balance" type="number" required>
  The new absolute balance to assign to the wallet. The current balance is overwritten entirely with this value.
</ParamField>

## Request Body — PUT

<ParamField body="amount" type="number" required>
  The amount to add to the current wallet balance. Use a positive number to credit the character and a negative number to debit them.
</ParamField>

## Response

Both methods return `200 OK` with the updated wallet object on success:

<ResponseField name="characterId" type="string">
  The Snowflake ID of the character this wallet belongs to.
</ResponseField>

<ResponseField name="balance" type="number">
  The wallet's balance after the update has been applied.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the wallet was first created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of when the wallet was last modified (reflects this update).
</ResponseField>

## Example Requests

```bash PATCH — Set absolute balance theme={null}
curl -X PATCH "https://api.cacolombia.com/v1/users/112233445566778899/characters/998877665544332211/wallet" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"balance": 20000}'
```

```bash PUT — Apply transaction amount theme={null}
curl -X PUT "https://api.cacolombia.com/v1/users/112233445566778899/characters/998877665544332211/wallet" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000}'
```

## Example Response

```json theme={null}
{
  "characterId": "998877665544332211",
  "balance": 20000,
  "createdAt": "2024-03-15T10:00:00.000Z",
  "updatedAt": "2024-06-02T09:15:44.000Z"
}
```

## Error Responses

| Status | Description                                                                                                            |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `400`  | The request body is missing required fields or contains values of the wrong type (e.g., a string instead of a number). |
| `401`  | You are not authenticated. Provide a valid authorization token with your request.                                      |
| `403`  | Your account does not hold the `ADMINISTRATOR` permission.                                                             |
| `403`  | The target character's `idStatus` is not `approved`. Only approved characters have active wallets.                     |
| `404`  | No user was found for the given `userId`.                                                                              |
| `404`  | No character was found for the given `characterId` under that user.                                                    |