---
title: "codespar wallets"
description: "Wallets: balances, ledger, funding sources, execute, transfer, custody"
---

Wallets: balances, ledger, funding sources, execute, transfer, custody

15 commands in `@codespar/cli 0.16.0`.

Each one prints what its operation answered. [What a command prints](/docs/cli/reference#what-a-command-prints) has the rule, and [Configuration](/docs/cli/config#what-a-script-gets-when-a-command-fails) has the exit codes and the shape of a failure.

### `codespar wallets list`

List wallets in the caller's project. Optional filters: status, agent_id.

```bash
codespar wallets list
```

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |

`GET /v1/wallets` · [parameters, responses and refusals](/docs/api/reference/wallets#get-v1wallets)

### `codespar wallets create`

Create a per-agent wallet. Seeds a zero-balance row in the requested currency.

```bash
codespar wallets create --input '{"display_name":"Example","currency":"BRL","agent_id":"agt_0000000000000000","metadata":{}}'
```

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |
| `-i, --input <json>` | Request body as a JSON string |
| `-f, --input-file <path>` | Request body from a JSON file |

`POST /v1/wallets` · [parameters, responses and refusals](/docs/api/reference/wallets#post-v1wallets)

### `codespar wallets get`

Fetch a wallet plus its per-currency balances. Cross-tenant ids return 404.

```bash
codespar wallets get obj_0000000000000000
```

| argument | what it is |
|---|---|
| `<id>` | String. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |

`GET /v1/wallets/{id}` · [parameters, responses and refusals](/docs/api/reference/wallets#get-v1walletsid)

### `codespar wallets list-ledger`

Paginated ledger view, newest first. Cursor via `before_id`. Optional `kind` filter.

```bash
codespar wallets list-ledger obj_0000000000000000
```

| argument | what it is |
|---|---|
| `<id>` | String. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |

`GET /v1/wallets/{id}/ledger` · [parameters, responses and refusals](/docs/api/reference/wallets#get-v1walletsidledger)

### `codespar wallets create-ledger`

Post a ledger entry. Admin role. Idempotent on (wallet_id, attempt_id, kind) and (wallet_id, kind, external_ref). Returns 200 with the prior row on retry, 201 on fresh insert. `kind=fund` is accepted only in a test project; in a live project it is refused with 409 `fund_requires_test_project` and nothing is written, because a live wallet is credited only by a real Pix, TED or provider receipt.

```bash
codespar wallets create-ledger obj_0000000000000000 --input '{"wallet_id":"wlt_0000000000000000","org_id":"org_0000000000000000","currency":"BRL","amount_minor":"1000","kind":"fund","metadata":{}}'
```

| argument | what it is |
|---|---|
| `<id>` | String. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |
| `-i, --input <json>` | Request body as a JSON string |
| `-f, --input-file <path>` | Request body from a JSON file |

`POST /v1/wallets/{id}/ledger` · [parameters, responses and refusals](/docs/api/reference/wallets#post-v1walletsidledger)

### `codespar wallets list-funding-sources`

List funding-source bindings for this wallet.

```bash
codespar wallets list-funding-sources obj_0000000000000000
```

| argument | what it is |
|---|---|
| `<id>` | String. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |

`GET /v1/wallets/{id}/funding-sources` · [parameters, responses and refusals](/docs/api/reference/wallets#get-v1walletsidfunding-sources)

### `codespar wallets create-funding-sources`

Bind a connected_accounts row as a funding rail for this wallet. Admin role. The funding bridge converts the connection's webhook events into kind=fund ledger entries.

```bash
codespar wallets create-funding-sources obj_0000000000000000 --input '{"connection_id":"conn_0000000000000000","currency":"BRL","metadata":{}}'
```

| argument | what it is |
|---|---|
| `<id>` | String. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |
| `-i, --input <json>` | Request body as a JSON string |
| `-f, --input-file <path>` | Request body from a JSON file |

`POST /v1/wallets/{id}/funding-sources` · [parameters, responses and refusals](/docs/api/reference/wallets#post-v1walletsidfunding-sources)

### `codespar wallets delete-funding-sources`

Unbind a funding source. Admin role.

```bash
codespar wallets delete-funding-sources obj_0000000000000000 conn_0000000000000000 BRL
```

| argument | what it is |
|---|---|
| `<id>` | String. |
| `<connection_id>` | String. |
| `<currency>` | One of `BRL`, `USD`, `MXN`, `COP`, `ARS`, `USDC`, `BRLA`. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |

`DELETE /v1/wallets/{id}/funding-sources/{connection_id}/{currency}` · [parameters, responses and refusals](/docs/api/reference/wallets#delete-v1walletsidfunding-sourcesconnection_idcurrency)

### `codespar wallets execute`

Drive the F2.M4 gateway lifecycle: policy → mandate → wallet hold → route → execute → wallet settle → audit. Admin role. HTTP status mirrors the GatewayPaymentResult.status (200 completed, 402 requires-approval, 403 denied, 422 failed).

```bash
codespar wallets execute obj_0000000000000000 --input-file body.json
```

```json title="body.json"
{
  "amount": 1000,
  "currency": "BRL",
  "target_currency": "USD",
  "preferred_method": "string",
  "recipient": "string",
  "description": "string",
  "mandate_id": "mandate_0000000000000000",
  "purpose": "string",
  "attempt_id": "attempt_0000000000000000",
  "metadata": {}
}
```

| argument | what it is |
|---|---|
| `<id>` | String. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |
| `-i, --input <json>` | Request body as a JSON string |
| `-f, --input-file <path>` | Request body from a JSON file |

`POST /v1/wallets/{id}/execute` · [parameters, responses and refusals](/docs/api/reference/wallets#post-v1walletsidexecute)

### `codespar wallets list-recon-anomalies`

List reconciliation anomalies the engine has flagged. Default status filter is `open`.

```bash
codespar wallets list-recon-anomalies obj_0000000000000000
```

| argument | what it is |
|---|---|
| `<id>` | String. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |

`GET /v1/wallets/{id}/recon-anomalies` · [parameters, responses and refusals](/docs/api/reference/wallets#get-v1walletsidrecon-anomalies)

### `codespar wallets create-recon-anomalies`

Operator marks an open anomaly as `resolved` or `dismissed`. Admin role. Idempotent on the partial unique covering open rows.

```bash
codespar wallets create-recon-anomalies obj_0000000000000000 string --input '{"status":"resolved","note":"string"}'
```

| argument | what it is |
|---|---|
| `<id>` | String. |
| `<aid>` | String. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |
| `-i, --input <json>` | Request body as a JSON string |
| `-f, --input-file <path>` | Request body from a JSON file |

`POST /v1/wallets/{id}/recon-anomalies/{aid}` · [parameters, responses and refusals](/docs/api/reference/wallets#post-v1walletsidrecon-anomaliesaid)

### `codespar wallets receive`

How to put money into a wallet, per rail

```bash
codespar wallets receive obj_0000000000000000
```

| argument | what it is |
|---|---|
| `<id>` | The wallet id. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |

`GET /v1/wallets/{id}/receive` · [parameters, responses and refusals](/docs/api/reference/wallets#get-v1walletsidreceive)

### `codespar wallets custody`

What the ledger attributed against what the address actually holds

```bash
codespar wallets custody obj_0000000000000000
```

| argument | what it is |
|---|---|
| `<id>` | The wallet id. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |

`GET /v1/wallets/{id}/custody` · [parameters, responses and refusals](/docs/api/reference/wallets#get-v1walletsidcustody)

### `codespar wallets transfer`

Withdraw from a consumer wallet under the consumer's signed mandate

```bash
codespar wallets transfer obj_0000000000000000 --input-file body.json
```

```json title="body.json"
{
  "currency": "BRL",
  "to_address": "string",
  "amount_minor": 1000,
  "idempotency_key": "string",
  "signature": "string",
  "agent_id": "agt_0000000000000000",
  "purpose": "string"
}
```

| argument | what it is |
|---|---|
| `<id>` | The wallet id. Must be consumer-scoped. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |
| `-i, --input <json>` | Request body as a JSON string |
| `-f, --input-file <path>` | Request body from a JSON file |

`POST /v1/wallets/{id}/transfer` · [parameters, responses and refusals](/docs/api/reference/wallets#post-v1walletsidtransfer)

### `codespar wallets statement-import`

Hand the reconciler a bank statement

```bash
codespar wallets statement-import obj_0000000000000000 --input-file body.json
```

```json title="body.json"
{
  "source": "string",
  "entries": [
    {
      "provider_event_id": "providerevent_0000000000000000",
      "amount_minor": 1000,
      "currency": "BRL",
      "occurred_at": "2026-01-15T12:00:00.000Z",
      "memo": "string"
    }
  ]
}
```

| argument | what it is |
|---|---|
| `<id>` | The wallet whose ledger these lines will be matched against. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |
| `-i, --input <json>` | Request body as a JSON string |
| `-f, --input-file <path>` | Request body from a JSON file |

`POST /v1/wallets/{id}/statement-import` · [parameters, responses and refusals](/docs/api/reference/wallets#post-v1walletsidstatement-import)