Preview · v1

The Ligo API reference

One base URL and one format for every bank. Responses are JSON in UTF-8, with amounts as decimals next to their currency and dates in ISO 8601.

REST
JSON
Client-held credentials
Zero custody

https://api.ligoapi.com/v1

This reference is a preview

Ligo is in its pilot phase. This page describes the API as designed for version 1: paths, fields and examples are illustrative and can change before the final reference is published. If you integrate during the pilot, we do it with you.

Become a design partner

Authentication

Every request carries two separate credentials: one that identifies your organization to Ligo, and the one your bank issued to your company.

Ligo issues one API key per organization and hands it over during pilot onboarding. Send it in the Authorization header.

Your bank credentials stay under your control and Ligo does not store them. You can provide them in two ways:

On each request

Send them in the X-Bank-Credentials header. Ligo uses them for that call and discards them: they only ever exist in memory.

From your secret manager

Keep them in your own AWS Secrets Manager account and give Ligo a read-only role limited to that secret. Ligo reads them at call time, keeps them in memory for at most five minutes, and you can withdraw the access whenever you decide.

curl "https://api.ligoapi.com/v1/accounts?bank=banco_general" \  -H "Authorization: Bearer $LIGO_API_KEY" \  -H "X-Bank-Credentials: $BANK_CREDENTIALS"

Source and freshness

Every response carries two fields that tell you how the data was obtained and how recent it is.

Source and freshness fields
Field	Values	What it tells you
`source`	`api`, `file`	How Ligo obtained the data: `api` if it queried the bank’s API, `file` if it read a file the bank delivers.
`as_of`	ISO 8601 date and time	The moment the data was read at the bank.

Some banks deliver their information in files, as often as your company’s contract with them provides. In that case the data cannot be more recent than the latest file, and as_of tells you so.

GET /v1/accounts

Accounts

Returns the accounts that the bank credentials in the request give access to.

Accounts: request parameters
Parameter	Type	Description
`bank`	string	Bank identifier, for example `banco_general`.

{  "data": [    { "account": "····4821", "type": "checking", "currency": "USD" },    { "account": "····0975", "type": "savings", "currency": "USD" }  ],  "bank": "banco_general",  "source": "api",  "as_of": "2026-10-04T14:32:07-05:00"}

GET /v1/accounts/{account}/balances

Balances

Returns the balance of one account. The response separates the available balance (available) from the ledger balance (ledger): they do not always match, and reconciling depends on knowing which is which.

Balances: request parameters
Parameter	Type	Description
`account`	string	Account identifier, as it appears in the list of accounts.
`bank`	string	Bank identifier, for example `banco_general`.

{  "account": "····4821",  "bank": "banco_general",  "available": { "amount": "128450.75", "currency": "USD" },  "ledger": { "amount": "131200.00", "currency": "USD" },  "source": "api",  "as_of": "2026-10-04T14:32:07-05:00"}

GET /v1/accounts/{account}/transactions

Movements

Returns the movements of one account within a date range, most recent first and in pages. How far back you can query depends on each bank.

Movements: request parameters
Parameter	Type	Description
`account`	string	Account identifier, as it appears in the list of accounts.
`bank`	string	Bank identifier, for example `banco_general`.
`from`	date	First day of the range, as `YYYY-MM-DD`.
`to`	date	Last day of the range, as `YYYY-MM-DD`.
`cursor`	string	Cursor for the next page, taken from `next_cursor`.

{  "data": [    {      "id": "txn_7f3a91",      "date": "2026-10-03",      "amount": "-1250.00",      "currency": "USD",      "description": "ACH PAGO A PROVEEDOR"    },    {      "id": "txn_7f3a8c",      "date": "2026-10-02",      "amount": "8400.00",      "currency": "USD",      "description": "DEPOSITO EN CUENTA"    }  ],  "next_cursor": "cur_9a7b",  "bank": "banco_general",  "source": "api",  "as_of": "2026-10-04T14:32:07-05:00"}

Payments

Payments are not part of this reference yet. When they are, they will be executed at your bank, with your credentials and under your bank’s controls: Ligo does not hold funds.

See what works today at each bank

Errors

Every bank reports failures its own way. Ligo translates them into one set of types and keeps the bank’s original error in details, so your team can diagnose.

Error types
Type	What it means	What to do
`bank_unavailable`	The bank did not respond or is out of service.	Try again later.
`bank_auth_failed`	The bank rejected the bank credentials.	Check with your bank that they are still valid.
`credential_unavailable`	Ligo could not obtain the bank credentials.	Check the `X-Bank-Credentials` header or the access to your secret manager.
`rate_limited`	The connection reached its call limit.	Wait for the period to renew before retrying.
`not_supported`	The bank does not offer that feature.	Check the coverage by bank.
`stale_source`	The bank’s latest file is older than expected.	Check `as_of` and ask your bank about the file delivery.

{  "error": {    "type": "bank_auth_failed",    "details": { "bank": "banco_general", "status": 401 }  }}

Limits

Each bank sets a call quota for your company’s credentials. So that your integration does not exhaust it, Ligo gives each bank connection an hourly and a daily call budget, set below the bank’s quota.

The limit has two steps: first a warning, then a stop. Once the budget is reached, calls return rate_limited until the period renews.

Identical calls that arrive at the same time are resolved with a single query to the bank and use no extra quota.

The values depend on each bank and are confirmed during pilot onboarding.