Swaps

A swap converts money from one of an organization’s balances to another, for example from USD to EUR. The money stays in the organization. Nothing is sent to anyone else, so no approval request is created; instead, the person confirms the swap with step-up.

What you can do

• Get a swap quote that fixes the price for five minutes.
• Execute the quote, with the person’s step-up.
• Read a swap afterwards.
• Read an indicative rate for converting a stablecoin deposit into US dollars, or US dollars into a stablecoin payout.

The sequence

1. See which currencies can be swapped

listOrganizationCurrencies marks each currency that can be swapped with convert; see Accounts and balances. Offer a pair only when both currencies have convert set to true.

curl -s "$ELE_API_BASE/api/v1/organizations/$ORGANIZATION_ID/currencies" \
  -H "Authorization: Bearer $ELE_TOKEN"

2. Get a swap quote

preflightSwap prices a swap. Fix one side with lock_side and amount, and name the other side’s currency in counter_currency:

• lock_side: "source": amount is what leaves the organization’s balance. The quote works out what arrives.
• lock_side: "target": amount is what arrives. The quote works out what leaves.

curl -s "$ELE_API_BASE/api/v1/swaps/preflight" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"organization_id\": \"$ORGANIZATION_ID\",
       \"lock_side\": \"source\",
       \"amount\": {\"amount\": \"1000.00\", \"currency\": \"USD\"},
       \"counter_currency\": \"EUR\"}"

{
  "quote_id": "0190f1c2-…",
  "source_amount": "1000.00",
  "target_amount": "917.42",
  "rate": "0.91742",
  "market_state": "open",
  "expires_at": "2026-10-09T10:05:00Z"
}

source_amount leaves the source balance and target_amount arrives in the target balance, after Ele’s fee. Show the person these two amounts. rate includes every charge and is not rounded: round it for display, and never use it to work out an amount yourself. See Money.

market_state is closed between 17:00 on Friday and 17:00 on Sunday, New York time, when currency markets are shut. Ele still quotes then, but at a different spread from when markets are open.

Getting a quote moves no money. You can get as many as you like.

A quote lasts five minutes. Execute it before expires_at, or get a new one.

3. Execute the swap

executeSwap carries out the quote. It needs step-up: the person must confirm, right then, that they are present. The first call answers 403 step_up_required; complete the challenge with the person and call again within the step-up window. See Step-up and approvals.

curl -s "$ELE_API_BASE/api/v1/swaps/execute" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"quote_id\": \"$QUOTE_ID\"}"

{
  "swap_id": "0190f1c4-…",
  "quote_id": "0190f1c2-…",
  "source_currency": "USD",
  "target_currency": "EUR",
  "source_amount": "1000.00",
  "target_amount": "917.42",
  "rate": "0.91742",
  "market_state": "open",
  "executed_at": "2026-10-09T10:02:31Z"
}

The swap is complete when the call returns: both balances have changed. It appears in listTransactions as a fiat_swap transaction.

Send an Idempotency-Key, created once for this swap and kept for every retry. A retry with the same key returns the same swap and does not convert twice, even after a 500. See Idempotency.

A quote executes once. Executing it again under a different key is refused with 409 already_executed.

4. Read the swap

getSwap returns the same object later:

curl -s "$ELE_API_BASE/api/v1/swaps/$SWAP_ID" \
  -H "Authorization: Bearer $ELE_TOKEN"

Stablecoin conversion rates

Stablecoin deposits are credited to the organization in US dollars, and stablecoin payouts are paid from US dollars. getConversionQuote shows the rate for either direction, for USDC and USDT:

• direction=deposit: a stablecoin arriving, credited as US dollars.
• direction=withdrawal: US dollars paid out as a stablecoin.

curl -s "$ELE_API_BASE/api/v1/conversions/quote?organization_id=$ORGANIZATION_ID&coin_id=$COIN_ID&direction=deposit" \
  -H "Authorization: Bearer $ELE_TOKEN"

coin_id is the coin’s ID, such as coin.id from listDepositAddresses. base_currency is the coin and quote_currency is USD. net_rate is the rate after all fees; additive_fees lists the fees one by one.

This quote is indicative only. It cannot be executed and does not reserve a rate.

States

A swap has no states to follow: once executeSwap returns, it is done. Only the quote changes:

Quote	Meaning	What you do
Before expires_at	It can be executed.	Execute it, or let it expire.
After expires_at	It can no longer be executed.	Get a new quote.
Executed	It became a swap.	Read the swap with getSwap.

Step-up and approvals

Call	Needs
preflightSwap, getSwap, getConversionQuote	Neither.
executeSwap	Step-up. No approval request.

An API key can never complete step-up, so swaps need a person’s session.

Who can do what

Operation	Roles
preflightSwap, executeSwap, getSwap	Owner, admin
getConversionQuote	Owner, admin, member

A member cannot swap. executeSwap and getSwap answer 404 not_found, not 403, when the person may not see the quote or swap.

What to poll

Nothing. A swap completes inside executeSwap. Read the balances afterwards with getOrganizationBalance.

Common errors

Status	type	When	What to do
403	step_up_required	executeSwap without an open step-up window.	Complete step-up with the person, then call again with the same key.
404	not_found	The quote, swap or coin_id is unknown, or the person may not see it.	Check the ID and the person’s role.
409	already_executed	The quote was already executed under another key.	Read the earlier swap, or get a new quote.
422	not_enabled	Swaps are not turned on for this organization.	Contact Ele support.
422	corridor_unavailable	Ele does not swap between these two currencies.	Offer only currencies with convert set.
422	stale_rate	Ele has no recent enough exchange rate to quote.	Try again later.
422	amount_too_small	The amount is too small to quote once fees are taken.	Ask for a larger amount.
422	no_matching_fee_rule	Ele has no fee set for this pair on the organization’s plan.	Contact Ele support.
422	quote_expired	executeSwap after expires_at.	Get a new quote.
422	insufficient_funds	The source balance does not cover source_amount.	Add money, or swap less.
422	organization_paused, organization_banned	The organization cannot move money.	Contact Ele support.
422	unsupported_conversion_coin	getConversionQuote for a coin other than USDC or USDT.	Ask only for those two.

For other types, see Errors.