Wallets

Available from @codespar/sdk 0.12.0; the version on npm is 0.12.0. Every example on this page is compiled against the installed package when these docs build: a call that does not type-check fails the build.

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 {  } from "@codespar/sdk";

const  = new ({ : .. });

GET `/v1/wallets`

GET/v1/wallets

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

const  = await ..("/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  = await ..("/v1/wallets", {
  : {
    : "Example",
    : "BRL",
    : {}
  }
});

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  = await ..("/v1/wallets/{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  = await ..("/v1/wallets/{id}/custody", {
  : {
    : "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  = await ..("post", "/v1/wallets/{id}/execute", {
  : {
    : "wlt_0000000000000000"
  },
  : {
    : 1000,
    : "BRL",
    : "USD",
    : "string",
    : "string",
    : "string",
    : "mandate_0000000000000000",
    : "string",
    : "attempt_0000000000000000",
    : {}
  }
});
// 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 (.) {
  .(.);
}

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  = await ..("/v1/wallets/{id}/funding-sources", {
  : {
    : "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  = await ..("/v1/wallets/{id}/funding-sources", {
  : {
    : "wlt_0000000000000000"
  },
  : {
    : "conn_0000000000000000",
    : "BRL",
    : {}
  }
});

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  = await ..("/v1/wallets/{id}/funding-sources/{connection_id}/{currency}", {
  : {
    : "wlt_0000000000000000",
    : "conn_0000000000000000",
    : "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  = await ..("/v1/wallets/{id}/ledger", {
  : {
    : "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  = await ..("/v1/wallets/{id}/ledger", {
  : {
    : "wlt_0000000000000000"
  },
  : {
    : "wlt_0000000000000000",
    : "org_0000000000000000",
    : "BRL",
    : "1000",
    : "fund",
    : {},
    : null,
    : null,
    : null
  }
});

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  = await ..("/v1/wallets/{id}/receive", {
  : {
    : "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  = await ..("/v1/wallets/{id}/recon-anomalies", {
  : {
    : "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  = await ..("/v1/wallets/{id}/recon-anomalies/{aid}", {
  : {
    : "wlt_0000000000000000",
    : "string"
  },
  : {
    : "resolved",
    : "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  = await ..("post", "/v1/wallets/{id}/statement-import", {
  : {
    : "wlt_0000000000000000"
  },
  : {
    : "string",
    : [
      {
        : "providerevent_0000000000000000",
        : 1000,
        : "BRL",
        : "2026-01-15T12:00:00.000Z",
        : "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 (.) {
  .(.);
}

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  = await ..("post", "/v1/wallets/{id}/transfer", {
  : {
    : "wlt_0000000000000000"
  },
  : {
    : "BRL",
    : "string",
    : 1000,
    : "string",
    : "string",
    : "agt_0000000000000000",
    : "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 (.) {
  .(.);
}

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

Wallets

On this page