Balances

Retrieve consolidated and per-chain balances.

Balances are read-only through the API. Move value by creating payouts or swaps rather than adjusting a balance directly.

Retrieve all balances#

bash

curl -s "$JUICEPAY_URL/v1/balances" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

json

{
  "object": "list",
  "data": [
    {
      "asset": "USDC",
      "available": "312904.180000",
      "pending": "4210.000000",
      "reserved": "0.000000",
      "chains": ["base", "solana", "arbitrum", "polygon"],
      "updated": "2026-08-19T09:12:44Z"
    }
  ],
  "as_of": "2026-08-19T09:14:02Z"
}

Retrieve one balance#

bash

curl -s "$JUICEPAY_URL/v1/balances/USDC" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

Balance fields#

Field	Type	Meaning
`asset`	string	Asset ticker.
`available`	decimal string	Spendable now, net of reserved funds.
`pending`	decimal string	Inbound value not yet final.
`reserved`	decimal string	Held against open limit orders and unapproved batches.
`chains`	string[]	Networks contributing to this balance.
`updated`	timestamp	When the underlying holdings last changed.

Per-chain breakdown#

bash

curl -s "$JUICEPAY_URL/v1/balances/USDC?group_by=chain" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

json

{
  "asset": "USDC",
  "available": "312904.180000",
  "by_chain": [
    { "chain": "base", "amount": "184320.550000", "available": "184320.550000" },
    { "chain": "solana", "amount": "96004.100000", "available": "96004.100000" },
    { "chain": "arbitrum", "amount": "21891.510000", "available": "21891.510000" },
    { "chain": "polygon", "amount": "10688.020000", "available": "10688.020000" }
  ]
}

Use this when you need to reason about consolidation cost. The sum of by_chain always equals the top-level available.

Ledger entries#

bash

curl -s "$JUICEPAY_URL/v1/ledger_entries?asset=USDC&limit=3" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

json

{
  "object": "list",
  "data": [
    {
      "id": "le_7hQ2mN",
      "direction": "credit",
      "asset": "USDC",
      "amount": "4250.000000",
      "chain": "base",
      "source": "payment_intent:pi_9fK2xQ",
      "created": "2026-08-19T09:14:02Z"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_2xNpRt8kL3"
}

Reserved funds#

A balance has money reserved against a working limit order or a batch awaiting approval. Reserved funds are not available and cannot be spent twice. When the batch is rejected or the order expires, the reservation is released and available rises.

If you are debugging "why can I not send more", compare available with reserved before assuming a bug.

Webhook#

Subscribe to balance.updated if you mirror balances into your own systems. It fires on every change with the new figures, which is cheaper than polling — and as_of lets you detect and discard out-of-order deliveries.

as_of reflects when the snapshot was computed, not when you received it. Compare it against your stored as_of, never against wall-clock time.