Wallets

Available from @codespar/sdk 0.12.0, which is not on npm yet. The published version today is 0.11.0, and it has no cs.api; 0.12.0 is on the main branch of codespar-core. The examples below are not compiled against the installed package for that reason.

Every call below is cs.api reaching one operation of the OpenAPI document this page was generated from; the REST client overview explains request, response, the option bag and the errors. The values are placeholders shaped by the document.

import { CodeSpar } from "@codespar/sdk";

const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY });

GET `/v1/wallets`

GET/v1/wallets

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

const result = await cs.api.get("/v1/wallets");

Parameters, body and every documented response: GET /v1/wallets in the HTTP reference.

POST `/v1/wallets`

POST/v1/wallets

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

const result = await cs.api.post("/v1/wallets", {
  body: {
    display_name: "Example",
    currency: "BRL",
    metadata: {}
  }
});

Parameters, body and every documented response: POST /v1/wallets in the HTTP reference.

GET `/v1/wallets/{id}`

GET/v1/wallets/{id}

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

const result = await cs.api.get("/v1/wallets/{id}", {
  path: {
    id: "wlt_0000000000000000"
  }
});

Parameters, body and every documented response: GET /v1/wallets/{id} in the HTTP reference.

GET `/v1/wallets/{id}/custody`

GET/v1/wallets/{id}/custody

What the ledger attributed against what the address actually holds

const result = await cs.api.get("/v1/wallets/{id}/custody", {
  path: {
    id: "wlt_0000000000000000"
  }
});

Parameters, body and every documented response: GET /v1/wallets/{id}/custody in the HTTP reference.

POST `/v1/wallets/{id}/execute`

POST/v1/wallets/{id}/execute

Moves money

policy → mandate → wallet hold → route → execute → wallet settle → audit

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

const r = await cs.api.response("post", "/v1/wallets/{id}/execute", {
  path: {
    id: "wlt_0000000000000000"
  },
  body: {
    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: {}
  }
});
// r.status is one of the documented statuses (200, 402, 403, 422),
// each with its own body shape in r.data; nothing here throws on 402.
if (r.ok) {
  console.log(r.data);
}

Parameters, body and every documented response: POST /v1/wallets/{id}/execute in the HTTP reference.

GET `/v1/wallets/{id}/funding-sources`

GET/v1/wallets/{id}/funding-sources

List funding-source bindings for this wallet.

const result = await cs.api.get("/v1/wallets/{id}/funding-sources", {
  path: {
    id: "wlt_0000000000000000"
  }
});

Parameters, body and every documented response: GET /v1/wallets/{id}/funding-sources in the HTTP reference.

POST `/v1/wallets/{id}/funding-sources`

POST/v1/wallets/{id}/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.

const result = await cs.api.post("/v1/wallets/{id}/funding-sources", {
  path: {
    id: "wlt_0000000000000000"
  },
  body: {
    connection_id: "conn_0000000000000000",
    currency: "BRL",
    metadata: {}
  }
});

Parameters, body and every documented response: POST /v1/wallets/{id}/funding-sources in the HTTP reference.

DELETE `/v1/wallets/{id}/funding-sources/{connection_id}/{currency}`

DELETE/v1/wallets/{id}/funding-sources/{connection_id}/{currency}

Unbind a funding source. Admin role.

const result = await cs.api.delete("/v1/wallets/{id}/funding-sources/{connection_id}/{currency}", {
  path: {
    id: "wlt_0000000000000000",
    connection_id: "conn_0000000000000000",
    currency: "BRL"
  }
});

Parameters, body and every documented response: DELETE /v1/wallets/{id}/funding-sources/{connection_id}/{currency} in the HTTP reference.

GET `/v1/wallets/{id}/ledger`

GET/v1/wallets/{id}/ledger

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

const result = await cs.api.get("/v1/wallets/{id}/ledger", {
  path: {
    id: "wlt_0000000000000000"
  }
});

Parameters, body and every documented response: GET /v1/wallets/{id}/ledger in the HTTP reference.

POST `/v1/wallets/{id}/ledger`

POST/v1/wallets/{id}/ledger

Moves money

Post a ledger entry.

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.

const result = await cs.api.post("/v1/wallets/{id}/ledger", {
  path: {
    id: "wlt_0000000000000000"
  },
  body: {
    wallet_id: "wlt_0000000000000000",
    org_id: "org_0000000000000000",
    currency: "BRL",
    amount_minor: "1000",
    kind: "fund",
    metadata: {}
  }
});

Parameters, body and every documented response: POST /v1/wallets/{id}/ledger in the HTTP reference.

GET `/v1/wallets/{id}/receive`

GET/v1/wallets/{id}/receive

How to put money into a wallet, per rail

const result = await cs.api.get("/v1/wallets/{id}/receive", {
  path: {
    id: "wlt_0000000000000000"
  }
});

Parameters, body and every documented response: GET /v1/wallets/{id}/receive in the HTTP reference.

GET `/v1/wallets/{id}/recon-anomalies`

GET/v1/wallets/{id}/recon-anomalies

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

const result = await cs.api.get("/v1/wallets/{id}/recon-anomalies", {
  path: {
    id: "wlt_0000000000000000"
  }
});

Parameters, body and every documented response: GET /v1/wallets/{id}/recon-anomalies in the HTTP reference.

POST `/v1/wallets/{id}/recon-anomalies/{aid}`

POST/v1/wallets/{id}/recon-anomalies/{aid}

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

const result = await cs.api.post("/v1/wallets/{id}/recon-anomalies/{aid}", {
  path: {
    id: "wlt_0000000000000000",
    aid: "string"
  },
  body: {
    status: "resolved",
    note: "string"
  }
});

Parameters, body and every documented response: POST /v1/wallets/{id}/recon-anomalies/{aid} in the HTTP reference.

POST `/v1/wallets/{id}/statement-import`

POST/v1/wallets/{id}/statement-import

Hand the reconciler a bank statement

const r = await cs.api.response("post", "/v1/wallets/{id}/statement-import", {
  path: {
    id: "wlt_0000000000000000"
  },
  body: {
    source: "string",
    entries: [
      {
        provider_event_id: "providerevent_0000000000000000",
        amount_minor: 1000,
        currency: "BRL",
        occurred_at: "2026-01-15T12:00:00.000Z",
        memo: "string"
      }
    ]
  }
});
// r.status is one of the documented statuses (200, 403),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

Parameters, body and every documented response: POST /v1/wallets/{id}/statement-import in the HTTP reference.

POST `/v1/wallets/{id}/transfer`

POST/v1/wallets/{id}/transfer

Moves money

Moves money OUT of a consumer-scoped wallet

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

const r = await cs.api.response("post", "/v1/wallets/{id}/transfer", {
  path: {
    id: "wlt_0000000000000000"
  },
  body: {
    currency: "BRL",
    to_address: "string",
    amount_minor: 1000,
    idempotency_key: "string",
    signature: "string",
    agent_id: "agt_0000000000000000",
    purpose: "string"
  }
});
// r.status is one of the documented statuses (200, 403, 422),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

Parameters, body and every documented response: POST /v1/wallets/{id}/transfer in the HTTP reference.

Wallets

On this page