API reference

Conversions

A conversion changes one of the merchant's balances into another asset or network, wallet to wallet. It moves the merchant's own funds through a venue (an outside exchange route), so it is requested by the API and approved with a passkey like a payout.

No venue is ever chosen silently. GET /v1/conversions/offers returns every venue's offer or refusal for the pair; you pass the venue you choose. At approval the offer is quoted again and the approver sees the final figures; the conversion is refused if the fresh output is below to.amount_minimum (max_slippage_bps, default 50 = 0.5%, range 0.1% to 3%). Offers are listed by guaranteed minimum, highest first; none is preselected.

Venues: relay (between EVM balances, and from Solana, TRON or Bitcoin into the settlement asset), kyberswap (same EVM network), thorchain (Bitcoin, Litecoin, Dogecoin into a stablecoin or ETH), sideshift (any pair the others lack; it is custodial between deposit and payout and the offer says so), rubic and across (extra cross-network EVM routes). A conversion always pays the merchant's own wallet, set by the server; paying anyone else is a payout. While a conversion is routed, the value is with the venue, a third party; Orrerie never holds it. confirmed means the output is proved in the merchant's wallet at or above the signed minimum; a venue's "success" is not proof.

The `conversion_offer` object

JSON

{
  "object": "conversion_offer",
  "venue": "relay",
  "available": true,
  "refusal_reason": null,
  "from": {
    "asset": "bitcoin:btc",
    "amount": "0.01000000"
  },
  "to": {
    "asset": "base:usdc",
    "amount_estimated": "1168.420000"
  },
  "rate": "116842.00",
  "fees": [
    {
      "kind": "route_fee",
      "amount": "1.38",
      "currency": "USD"
    },
    {
      "kind": "network_fee",
      "amount": "0.61",
      "currency": "USD"
    }
  ],
  "estimated_seconds": 900,
  "expires_at": "2026-10-12T11:01:00.000Z"
}

The `conversion` object

JSON

{
  "id": "cv_ban2ezvpwf4j4d09h4htv42j",
  "object": "conversion",
  "livemode": true,
  "created": "2026-10-12T11:00:30.000Z",
  "updated": "2026-10-12T11:00:30.000Z",
  "status": "awaiting_approval",
  "pending_reason": null,
  "venue": "relay",
  "venue_progress": null,
  "from": {
    "wallet": "wal_zjdztygt4g73zm0cdcjjf43k",
    "asset": "bitcoin:btc",
    "amount": "0.01000000"
  },
  "to": {
    "wallet": "wal_bsfw07hymawmda7gg8jsyy3g",
    "asset": "base:usdc",
    "amount_estimated": "1168.420000",
    "amount_minimum": "1162.577900",
    "amount_received": null
  },
  "rate": "116842.00",
  "max_slippage_bps": 50,
  "fees": [
    {
      "kind": "route_fee",
      "amount": "1.38",
      "currency": "USD"
    },
    {
      "kind": "network_fee",
      "amount": "0.61",
      "currency": "USD"
    }
  ],
  "in_transit_notice": "While a conversion is being routed it is held by Relay, a separate company. Orrerie never holds it.",
  "requested_by": {
    "type": "api_key",
    "id": "key_6e3gg2c6ea176xxdek2nar6v"
  },
  "approved_by": null,
  "approval_url": "https://merchant.orrerie.com/approve/cv_ban2ezvpwf4j4d09h4htv42j",
  "approval_expires_at": "2026-10-19T11:00:30.000Z",
  "send_transaction_hash": null,
  "receive_transaction_hash": null,
  "failure_code": null,
  "cancellation_reason": null,
  "approved_at": null,
  "sent_at": null,
  "confirmed_at": null,
  "metadata": {}
}

Table: The conversion object
Field	Meaning
`pending_reason`	For a draft: approval_lapsed. Otherwise `null`.
`venue_progress`	The venue's own progress once sent: deposit_confirmed, payout_proved, refunding, refund_proved. A hint; status is the proof.
`status`	One of `draft`, `awaiting_approval`, `signed`, `sent`, `confirmed`, `failed`, `unknown`, `cancelled`.
`venue`	One of `relay`, `kyberswap`, `thorchain`, `sideshift`, `rubic`, `across`.

Every field

Fields of the `conversion_offer` object

Fields of the conversion_offer object
Field	Type	Meaning
`object`	string	The type of this object.
`venue`	string	The venue the offer is from.
`available`	boolean	`true` when the venue offers this conversion now.
`refusal_reason`	string or null	Why the venue offers nothing now; `null` when it makes an offer.
`from`	object	What would leave the merchant wallet.
`from.asset`	string	The asset converted.
`from.amount`	string	How much of it.
`to`	object	What would arrive.
`to.asset`	string	The asset received.
`to.amount_estimated`	string or null	About what would arrive; `null` when the venue offers nothing.
`rate`	string or null	Units of `to.asset` per unit of `from.asset`; `null` when the venue offers nothing.
`fees`	array of objects	What the conversion costs, one line per kind of fee.
`fees[].kind`	string	`route_fee` (the venue's) or `network_fee`.
`fees[].amount`	string	The fee, a decimal string.
`fees[].currency`	string	Always `USD`.
`estimated_seconds`	integer or null	About how long the conversion takes, in seconds; `null` when the venue offers nothing.
`expires_at`	string (date-time) or null	When the offer stops being honoured; `null` when the venue offers nothing.

Fields of the `conversion` object

Fields of the conversion 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.
`updated`	string (date-time)	When the object last changed.
`status`	string	One of `draft`, `awaiting_approval`, `signed`, `sent`, `confirmed`, `failed`, `unknown`, `cancelled`.
`pending_reason`	string or null	For a draft: approval_lapsed. Otherwise `null`.
`venue`	string	One of `relay`, `kyberswap`, `thorchain`, `sideshift`, `rubic`, `across`.
`venue_progress`	string or null	The venue's own progress once sent: deposit_confirmed, payout_proved, refunding, refund_proved. A hint; status is the proof.
`from`	object	What leaves the merchant wallet.
`from.wallet`	string	The `wal_` id of the wallet it leaves.
`from.asset`	string	The asset converted.
`from.amount`	string	How much of it.
`to`	object	What arrives.
`to.wallet`	string	The `wal_` id of the wallet it arrives in.
`to.asset`	string	The asset received.
`to.amount_estimated`	string	About what arrives, at the offer's rate.
`to.amount_minimum`	string	The least that may arrive: below it the conversion is refused at approval.
`to.amount_received`	string or null	What arrived, proved by the wallet's own chain read; `null` until then.
`rate`	string	Units of `to.asset` per unit of `from.asset` in the offer.
`max_slippage_bps`	integer	How far below the estimate the fresh quote at approval may be, in basis points.
`fees`	array of objects	What the conversion costs, one line per kind of fee.
`fees[].kind`	string	`route_fee` (the venue's) or `network_fee`.
`fees[].amount`	string	The fee, a decimal string.
`fees[].currency`	string	Always `USD`.
`in_transit_notice`	string	The sentence shown while the conversion is on its way at the venue.
`requested_by`	object	Who asked for it: an API key or a dashboard member.
`requested_by.type`	string	`api_key` or `member`.
`requested_by.id`	string	The id of the key (`key_…`) or the member (`mem_…`) that asked.
`approved_by`	string or null	The member who approved it with a passkey; `null` until approved.
`approval_url`	string or null	The dashboard page where an Owner or Finance member approves it; `null` once approved, cancelled or lapsed.
`approval_expires_at`	string (date-time)	When an unapproved request lapses to `draft`.
`send_transaction_hash`	string or null	The hash of the send from the merchant wallet; `null` until sent.
`receive_transaction_hash`	string or null	The hash of the transaction that delivered the result; `null` until it arrives.
`failure_code`	string or null	Why it failed (Money out lists the codes); `null` unless `status` is `failed` or `unknown`.
`cancellation_reason`	string or null	Why it was cancelled; `null` unless it was.
`approved_at`	string or null	When it was approved; `null` until then.
`sent_at`	string or null	When the send was broadcast; `null` until then.
`confirmed_at`	string or null	When the result was proved in the receiving wallet; `null` until then.
`metadata`	object	Up to 50 keys of your own data. Key up to 40 characters, value a string up to 500 characters. Never used by Orrerie; never put secrets or personal data here.

Endpoints

Events

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

Conversions

The conversion_offer object

The conversion object