Balances & rates

Read your organization's balances and quote conversion rates.

Get balances

GET /v1/balances — Scope: balances:read

Returns your organization's balance for each asset it holds — the available amount you can pay out and the held amount reserved by in-flight payouts. Takes no parameters.

Request

bash

curl https://api.caiboglobal.com/v1/balances \
  -H "X-API-Key: $CAIBO_API_KEY"

Response — 200 OK

json

{
  "object": "list",
  "data": [
    { "asset": "USDC", "available": "1200.00", "held": "25.00" },
    { "asset": "USDT", "available": "0", "held": "0" }
  ]
}

Field	Type	Description
`asset`	string	The asset, e.g. `USDC`.
`available`	string	Decimal amount available to pay out.
`held`	string	Decimal amount reserved by payouts that are in flight.

Errors

HTTP	type	code	When
401	authentication_error	api_key_missing / api_key_invalid	No key, or an unknown/revoked key.
403	permission_error	scope_insufficient	The key lacks `balances:read`.
429	rate_limit_error	rate_limited	Too many requests.

Get a rate

GET /v1/rates — Scope: balances:read

Returns the current conversion quote for a currency pair, including the effective rate (after spread) and the amount you'd receive for a given input amount. This is a read-only quote — it creates nothing.

Query parameters

Parameter	Type	Required	Description
`from_currency_id`	string	Yes	The source currency's internal id.
`to_currency_id`	string	Yes	The target currency's internal id.
`amount`	string	No	Decimal input amount to convert. Defaults to `0`.

from_currency_id and to_currency_id are internal currency identifiers. There is no currency-listing endpoint on v1 today; if you need the ids for your configured pairs, contact support.

Request

bash

curl "https://api.caiboglobal.com/v1/rates?from_currency_id=cur_cad&to_currency_id=cur_usdc&amount=100" \
  -H "X-API-Key: $CAIBO_API_KEY"

Response — 200 OK

json

{
  "object": "rate",
  "rate": "0.735",
  "effective_rate": "0.72765",
  "fee": "0.50",
  "amount_in": "100",
  "amount_out": "72.401175"
}

Field	Type	Description
`rate`	string	The base conversion rate.
`effective_rate`	string	The rate after applying the spread.
`fee`	string	The flat fee subtracted from the input before conversion.
`amount_in`	string	The input amount you supplied.
`amount_out`	string	The resulting amount: `max(0, amount_in − fee) × effective_rate`.

Errors

HTTP	type	code	When
400	invalid_request_error	bad_request	Missing `from_currency_id`/`to_currency_id`, or an invalid `amount`.
401	authentication_error	api_key_missing / api_key_invalid	No key, or an unknown/revoked key.
403	permission_error	scope_insufficient	The key lacks `balances:read`.
404	invalid_request_error	not_found	No active rate exists for the pair.
429	rate_limit_error	rate_limited	Too many requests.