API reference

Wallets and balances

Read-only. A merchant has exactly eleven wallets, one per network, created in one step at sign-up; the API cannot create, delete or change a wallet, an owner or a threshold. status is address_ready (nothing deployed), deploying, or active. Bitcoin, Litecoin and Dogecoin wallets are active from the start. Nine wallets can receive at once; a Solana or TRON wallet receives only after activation (two_of_three_in_force, display_state).

A balance read is the wallet's own chain read, made by the merchant's worker. If the worker is asleep the first call may answer 503 merchant_worker_waking with Retry-After: 2; retry.

What the API can and cannot do with money is set out in full in Money out. In one line: it reads everything, it requests refunds, payouts, conversions and saved addresses, and it can never sign, approve, or change where money goes.

The `wallet` object

JSON

{
  "id": "wal_bsfw07hymawmda7gg8jsyy3g",
  "object": "wallet",
  "livemode": true,
  "created": "2026-09-02T09:16:20.000Z",
  "wallet_set": "wset_6tnmbah49h3xpfbgefw5f2jz",
  "network": "base",
  "status": "address_ready",
  "display_state": "ready",
  "two_of_three_in_force": true,
  "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  "shape": "safe_1_4_1",
  "threshold": 2,
  "owner_count": 3,
  "can_receive": true,
  "can_send": true,
  "deployed": false,
  "deployment_note": "Deployed with the first approved send; the fee account pays.",
  "native_asset": "base:eth",
  "explorer_url": "https://basescan.org/address/0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
}

Table: The wallet object
Field	Meaning
`status`	address_ready (has an address; nothing deployed), deploying, active (deployed and can send). Values: `address_ready`, `deploying`, `active`.
`display_state`	`ready`, `not_activated` (a Solana or TRON wallet before activation), `not_enabled` (the network is not switched on yet), `deploying`, `active`.
`two_of_three_in_force`	`false` for a Solana or TRON wallet before activation: that address is then controlled by one key, so `address` is `null`, `can_receive` is `false`, and the wallet is not used for settlement or the direct rail. True for every other wallet from creation.
`network`	One of `ethereum`, `bsc`, `polygon`, `arbitrum`, `optimism`, `base`, `solana`, `tron`, `bitcoin`, `litecoin`, `dogecoin`.
`shape`	One of `safe_1_4_1`, `squads_vault`, `tron_permissions`, `p2wsh`, `p2sh_p2wsh`, `p2sh`.

The `balance` object

JSON

{
  "object": "balance",
  "wallet": "wal_bsfw07hymawmda7gg8jsyy3g",
  "network": "base",
  "asset": "base:usdc",
  "amount": "1284.500000",
  "incoming_unconfirmed": "0.000000",
  "reserved": "250.000000",
  "available": "1034.500000",
  "value": {
    "amount": "1284.37",
    "currency": "USD"
  },
  "as_of": "2026-10-12T09:29:58.000Z"
}

Table: The balance object
Field	Meaning
`reserved`	Held for money-out requests that are awaiting approval or in flight.
`available`	Amount minus reserved.

The `fee_account` object

JSON

{
  "id": "fa_z9x4m7aaz6zqhzgd0x1qg952",
  "object": "fee_account",
  "livemode": true,
  "created": "2026-09-02T09:16:20.000Z",
  "top_up_from_takings": true,
  "keys": [
    {
      "family": "evm",
      "address": "0x52908400098527886E0F7030069857D2E4169EE7",
      "balances": [
        {
          "network": "base",
          "asset": "base:eth",
          "amount": "0.000410000000000000",
          "value": {
            "amount": "1.02",
            "currency": "USD"
          },
          "low_mark": {
            "amount": "0.50",
            "currency": "USD"
          },
          "low": false
        }
      ]
    },
    {
      "family": "solana",
      "address": "4Nd1mYvQwC8eBtBMRZcQJ6pGZpUuPqiJvWx3nCkV8sXh",
      "balances": [
        {
          "network": "solana",
          "asset": "solana:sol",
          "amount": "0.000000000",
          "value": {
            "amount": "0.00",
            "currency": "USD"
          },
          "low_mark": {
            "amount": "0.50",
            "currency": "USD"
          },
          "low": true
        }
      ]
    },
    {
      "family": "tron",
      "address": "TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7",
      "balances": [
        {
          "network": "tron",
          "asset": "tron:trx",
          "amount": "0.000000",
          "value": {
            "amount": "0.00",
            "currency": "USD"
          },
          "low_mark": {
            "amount": "0.50",
            "currency": "USD"
          },
          "low": true
        }
      ]
    }
  ]
}

The `ledger_entry` object

JSON

{
  "id": "le_d1jr8qbcjryqrqt72pxzk44n",
  "object": "ledger_entry",
  "livemode": true,
  "created": "2026-10-11T14:09:55.764Z",
  "type": "payment",
  "wallet": "wal_bsfw07hymawmda7gg8jsyy3g",
  "asset": "base:usdc",
  "amount": "21.990000",
  "direction": "in",
  "value": {
    "amount": "21.99",
    "currency": "USD"
  },
  "order": "ord_0zymngngvf12b8b2cra7tb8e",
  "source": "pay_2pe50hae6w2jk4sp1rcq5pae",
  "transaction_hash": "0x27ca64c092a959c7edc525ed45e845b1de6a7590d173fd2fad9133c8a779a1e3",
  "description": "Order #1042"
}

Table: The ledger_entry object
Field	Meaning
`type`	One of `payment`, `provider_refund`, `refund`, `payout`, `withdrawal`, `conversion_out`, `conversion_in`, `network_fee`, `route_fee`, `fee_account_top_up`, `sweep`, `unmatched_payment`, `adjustment`.
`direction`	One of `in`, `out`.

Every field

Fields of the `wallet` object

Fields of the wallet object
Field	Type	Meaning
`two_of_three_in_force`	boolean	`false` for a Solana or TRON wallet before activation: that address is then controlled by one key, so address is `null`, can_receive is `false`, and the wallet is not used for settlement or the direct rail. `true` for every other wallet from creation.
`display_state`	string	What the dashboard shows. `not_activated`: Solana or TRON before activation. `not_enabled`: Orrerie has not switched this network on yet; address is `null`. One of `ready`, `not_activated`, `not_enabled`, `deploying`, `active`.
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`wallet_set`	string	The `wset_` id of the set of eleven wallets this one belongs to.
`network`	string	One of `ethereum`, `bsc`, `polygon`, `arbitrum`, `optimism`, `base`, `solana`, `tron`, `bitcoin`, `litecoin`, `dogecoin`.
`status`	string	address_ready (can receive), deploying, active (deployed and can send). One of `address_ready`, `deploying`, `active`.
`address`	string or null	The wallet's address; `null` in test mode, and before a Solana or TRON wallet is activated.
`shape`	string	One of `safe_1_4_1`, `squads_vault`, `tron_permissions`, `p2wsh`, `p2sh_p2wsh`, `p2sh`.
`threshold`	integer	How many signatures a send needs: 2.
`owner_count`	integer	How many keys can sign for it: 3.
`can_receive`	boolean	`true` when payments may be sent to it now.
`can_send`	boolean	`true` when money can leave it now.
`deployed`	boolean	`true` once the wallet's contract or account exists on its network.
`deployment_note`	string or null	What happens at the first send of a wallet not yet deployed; `null` for none.
`native_asset`	string	The asset id of the network's own coin.
`explorer_url`	string or null	The wallet's page on a public block explorer; `null` in test mode or without an address.

Fields of the `balance` object

Fields of the balance object
Field	Type	Meaning
`object`	string	The type of this object.
`wallet`	string	The `wal_` id of the wallet holding it.
`network`	string	The network of the wallet.
`asset`	string	The asset held.
`amount`	string	What the wallet holds, in the asset's own units.
`incoming_unconfirmed`	string	Payments seen on their way that are not yet confirmed, in the asset's own units.
`reserved`	string	Held for money-out requests that are awaiting approval or in flight.
`available`	string	Amount minus reserved.
`value`	object	What `amount` is worth now, in the currency asked for (US dollars by default).
`value.amount`	string	The value, a decimal string.
`value.currency`	string	The currency of the value.
`as_of`	string (date-time)	When the wallet's balance was last read from the chain.

Fields of the `fee_account` object

Fields of the fee_account object
Field	Type	Meaning
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`top_up_from_takings`	boolean	`true` when small orders on the settlement network refill the fee account.
`keys`	array of objects	The account's keys, one per network family. Empty in test mode, which shows no address at all (04 Test mode).
`keys[].family`	string	`evm`, `solana` or `tron`.
`keys[].address`	string	The fee account's address for that family.
`keys[].balances`	array of objects	What the address holds on each network it pays fees on.
`topup`	object	Whether the fee account fills itself from takings (Money out), so an integration can tell: a merchant with no orders that small must send the coin once.
`topup.enabled`	boolean	`true` when orders in eligible_order_range on the settlement network refill the fee account; the same as top_up_from_takings.
`topup.last`	string (date-time) or null	When a top-up's fill was last proved at the fee address; `null` when none ever was.
`topup.eligible_order_range`	array of strings	The smallest and largest order, in US dollars, that can refill the fee account: 1.00 and 10.00.

Fields of the `ledger_entry` object

Fields of the ledger_entry object
Field	Type	Meaning
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`type`	string	One of `payment`, `provider_refund`, `refund`, `payout`, `withdrawal`, `conversion_out`, `conversion_in`, `network_fee`, `route_fee`, `fee_account_top_up`, `sweep`, `unmatched_payment`, `adjustment`.
`wallet`	string or null	The `wal_` id of the wallet the entry moved; `null` when the fee account paid or received it.
`asset`	string	The asset that moved.
`amount`	string	How much moved, in the asset's own units.
`direction`	string	One of `in`, `out`.
`value`	object	What it was worth in US dollars at the time.
`value.amount`	string	The value, a decimal string.
`value.currency`	string	Always `USD`.
`order`	string or null	The `ord_` id of the order the entry belongs to; `null` for none.
`source`	string or null	The id of what made the entry: a payment, refund, payout, conversion or sweep; `null` for an adjustment.
`transaction_hash`	string or null	The hash of the transaction behind the entry; `null` when no transaction made it.
`description`	string	A short description of the entry, as the dashboard shows it.

Endpoints

Events

Webhook events whose data.object is an object of this page.

Wallets and balances

The wallet object

The balance object

The fee_account object

The ledger_entry object

Every field

Fields of the wallet object

Fields of the balance object

Fields of the fee_account object

Fields of the ledger_entry object

Endpoints

Events

The `wallet` object

The `balance` object

The `fee_account` object

The `ledger_entry` object

Fields of the `wallet` object

Fields of the `balance` object

Fields of the `fee_account` object

Fields of the `ledger_entry` object