> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.useroot.com/api-reference/treasury-api/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.useroot.com/_mcp/server.

# Treasury API

The **Treasury API** lets you work with your organization's main operating accounts: list onboarded accounts, read balance snapshots, review bank-reported activity, and initiate **account transfers** between accounts you control.

## Accounts

A **Treasury account** is a main operating account onboarded for your organization. Accounts are provisioned through onboarding; you do not create them through this API. You may update the display **label** via `POST /accounts/{account_id}/update-label`.

Use **List treasury accounts** for high-level metadata (identifier, label, currency). Use **Get treasury account balance** for the latest reported balance on a specific account. Use **List bank-reported transactions** for bank-ingested credits and debits on an account.

## Account transfers

An **Account transfer** moves funds between two treasury accounts you control. Specify the source and destination account IDs, amount, currency, and rail. Account transfers follow a status lifecycle similar to other money-movement products.

### Account transfer status lifecycle

| Status | Description |
|--------|-------------|
| `created` | The account transfer was created and is awaiting approval (when `auto_approve` is false). |
| `approved` | The account transfer has been approved and is queued for initiation. |
| `initiated` | The transfer has been submitted to the banking partner; funds are in transit. |
| `settled` | The transfer completed successfully. |
| `failed` | The transfer could not be completed. |

When `auto_approve` is `true`, a newly created account transfer moves through approval and initiation automatically. With async initiation enabled for your entity, create-with-`auto_approve` may return **202 Accepted** while bank processing continues in the background—poll list endpoints until status stabilizes.

To approve an account transfer created without `auto_approve`, use **`POST /account-transfers/{account_transfer_id}/approve`**.

## Simulating inbound credits (test entities)

For **test entities** with SIM treasury accounts, use **`POST /accounts/{account_id}/simulate-inbound-credit`** to seed an inbound credit on a specific account without running a payin or ingesting a BAI2 file. The credit appears on **List bank-reported transactions** for that account. Live entities receive bank lines only through bank ingestion.

## Pagination

List endpoints use cursor-based pagination. Pass `cursor` from `next_cursor` in the previous response, along with `limit` and `order`, to walk pages of results.

## Common error codes

| Error Code | Description |
|------------|-------------|
| `VALIDATION_ERROR` | Invalid query parameters or request body (including unsupported rail, incompatible currency, or invalid account pair). |
| `AUTHENTICATION_ERROR` | Missing or invalid API credentials. |
| `AUTHORIZATION_ERROR` | Credentials are valid but the action is not permitted. |
| `NOT_FOUND` | The requested treasury account, bank transaction, account transfer, or balance does not exist. |


## API Docs

- Treasury API [List treasury accounts](https://docs.useroot.com/api-reference/treasury-api/list-treasury-accounts.md)
- Treasury API [Get treasury account](https://docs.useroot.com/api-reference/treasury-api/get-treasury-account-by-id.md)
- Treasury API [Update treasury account label](https://docs.useroot.com/api-reference/treasury-api/update-treasury-account-label.md)
- Treasury API [Get treasury account balance](https://docs.useroot.com/api-reference/treasury-api/get-treasury-account-balance.md)
- Treasury API [List bank-reported transactions for a treasury account](https://docs.useroot.com/api-reference/treasury-api/list-treasury-account-bank-transactions.md)
- Treasury API [Get bank-reported transaction](https://docs.useroot.com/api-reference/treasury-api/get-treasury-account-bank-transaction-by-id.md)
- Treasury API [Simulate inbound credit](https://docs.useroot.com/api-reference/treasury-api/treasury-simulate-inbound-credit.md)
- Treasury API [Get rail options for account transfer](https://docs.useroot.com/api-reference/treasury-api/get-account-transfer-rail-options.md)
- Treasury API [Get account transfer conversion estimate](https://docs.useroot.com/api-reference/treasury-api/get-account-transfer-conversion-estimate.md)
- Treasury API [List account transfers](https://docs.useroot.com/api-reference/treasury-api/list-account-transfers.md)
- Treasury API [Create account transfer](https://docs.useroot.com/api-reference/treasury-api/create-account-transfer.md)
- Treasury API [Get account transfer](https://docs.useroot.com/api-reference/treasury-api/get-account-transfer-by-id.md)
- Treasury API [Approve account transfer](https://docs.useroot.com/api-reference/treasury-api/approve-account-transfer.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.useroot.com/openapi.json)
- [OpenAPI YAML](https://docs.useroot.com/openapi.yaml)