Create Sell Order

For the complete documentation index, see llms.txt. Append .md to any page URL for its markdown version.

Create an off-ramp order (crypto → fiat) for a customer. Returns a checkoutUrl to redirect or embed so the customer can complete their transaction.

Endpoint

POST /{partnerRef}/v2/sell

Request body

Field	Type	Required	Description
`crypto`	string	Yes	Cryptocurrency code the customer wants to sell (e.g., `ETH`, `USDT`).
`fiat`	string	Yes	Fiat currency the customer wants to receive (e.g., `AUD`, `EUR`).
`walletAddress`	string	Custodial flows	Customer's sending wallet address: where the crypto is sent from. Banxa screens this address and uses it as the refund address. Required for custodial flows, where it must match `sourceAddress` on confirmation. Recommended for all sell orders.
`redirectUrl`	string	Yes	URL or deep link to return the customer to after checkout. With the Native Wallet flow, Banxa also redirects here with the deposit details.
`paymentMethodId`	string	No	Pre-selects the payout method. If omitted, the customer chooses in checkout. See supported values below.
`fiatAmount`	string	Conditional	Fiat amount to receive. Either `fiatAmount` or `cryptoAmount` must be provided. Must be within the asset's minimum and maximum limits.
`cryptoAmount`	string	Conditional	Crypto amount to sell. Either `fiatAmount` or `cryptoAmount` must be provided. Must be within the asset's minimum and maximum limits.
`blockchain`	string	No	Blockchain network the crypto is sent on (e.g., `ETH`, `TRON`). If omitted, Banxa uses its default network for the coin.
`externalCustomerId`	string	Recommended	Your stable identifier for this customer. Enables returning customer recognition and reduces repeat KYC. See best practices.
`email`	string	No	Customer's email address.
`phoneNumber`	string	No	Customer's phone number.
`externalOrderId`	string	No	Your own order reference to attach to this transaction. Banxa stores it and returns it in order responses and webhooks for reconciliation. Some accounts require it to be unique.
`walletAddressTag`	string	No	Memo or tag of the customer's sending wallet, on chains that use one (e.g., memo for XLM, destination tag for XRP).
`discountCode`	string	No	Discount code to apply to the order.
`subPartnerId`	string	No	Identifier for a sub-partner or segment within your account (e.g., different sites or resellers).
`metadata`	string	No	Additional free-form data to attach to the order. Returned as-is in order responses and webhooks.
`ipBinding`	array	Conditional	The customer's IP address, so Banxa can check that checkout is opened from the same network. One item per IP version (`v4`, `v6`), at most two. Required once Banxa turns on IP binding for your account, unless you send `ipBindingOmitted`. See IP Binding.
`ipBinding[].method`	string	Yes	`hash` (the exact address, hashed) or `range` (the network the address is in).
`ipBinding[].family`	string	Yes	`v4` or `v6`.
`ipBinding[].value`	string	Yes	For `hash`: 64 hexadecimal characters. See Hashing the IP address. For `range`: an IPv4 `/24` or IPv6 `/64` network with the host part set to zero, such as `203.0.113.0/24` or `2001:db8:1234:5678::/64`.
`ipBindingOmitted`	string	Conditional	Send `private_relay` instead of `ipBinding` when the customer uses iCloud Private Relay. No other value is accepted. Never send both.
`originalUrl`	string	No	The `http` or `https` URL of the page the customer started the order on. Banxa stores it with the order. Longer than 2,048 characters is shortened, not rejected.

Payment method IDs (sell)

Value	Payout method
`payid-bank-transfer`	NPP Direct Entry bank transfer to a BSB and account number (AUD)
`sepa-bank-transfer`	SEPA bank transfer (EUR)
`interac-bank-transfer`	Interac (CAD)
`ach-bank-transfer`	ACH bank transfer (USD)
`gbp-bank-transfer`	Faster Payments bank transfer (GBP)
`debit-credit-card`	Card payout to a Visa or Mastercard debit or credit card (EUR, selected European countries)

→ See Supported Payment Methods for regions and the countries where card payouts are available.

Example requests

NPP Direct Entry (AUD)

curl -X POST "https://api.banxa-sandbox.com/{partnerRef}/v2/sell" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "crypto": "ETH",
    "blockchain": "ETH",
    "fiat": "AUD",
    "cryptoAmount": "0.5",
    "walletAddress": "0xcbf80ee36fbf03307962576f338fc50b942e0591",
    "redirectUrl": "https://yourapp.com/order-complete",
    "paymentMethodId": "payid-bank-transfer"
  }'

SEPA (EUR)

curl -X POST "https://api.banxa-sandbox.com/{partnerRef}/v2/sell" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "crypto": "ETH",
    "blockchain": "ETH",
    "fiat": "EUR",
    "cryptoAmount": "0.5",
    "walletAddress": "0xcbf80ee36fbf13307962576f338fc50b942e0591",
    "redirectUrl": "https://yourapp.com/order-complete",
    "paymentMethodId": "sepa-bank-transfer"
  }'

Response

201 Created

{
  "checkoutUrl": "https://partner.banxa.com/portal?expires=xxx&oid=xxx&signature=xxx",
  "id": "191fa5b4b1f45e1cf784422e09317d56",
  "externalOrderId": "a4b427ccb872a1744b317456bd0d165f",
  "externalCustomerId": "user_12345",
  "fiat": "AUD",
  "fiatAmount": "1000.00",
  "crypto": "ETH",
  "cryptoAmount": null,
  "blockchain": "ETH"
}

Field	Description
`checkoutUrl`	URL to redirect or embed for the customer to complete their transaction.
`id`	Banxa order ID. Store this for order lookup and reconciliation.
`externalOrderId`	Your order reference (`externalOrderId` from the request). Null if not provided.
`externalCustomerId`	The customer identifier you provided.
`fiat`	Fiat currency code (string).
`fiatAmount`	Fiat amount as a string.
`crypto`	Cryptocurrency code (string).
`cryptoAmount`	Crypto amount as a string. Null if not provided in the request.
`blockchain`	Blockchain network.

Use order lookup or webhooks to track the order after checkout.

IP binding

Sell orders use IP binding the same way as buy orders. Send the customer's IP address in ipBinding (or ipBindingOmitted for iCloud Private Relay customers) and Banxa checks it when checkout is opened. It's on for all new partners, and required on every sell order as well as every buy order.

"ipBinding": [
  { "method": "range", "family": "v4", "value": "203.0.113.0/24" }
]

→ See IP Binding for how to get the address, choose hash or range, and build the values.

Sending the crypto

After the customer submits their payout details, Banxa issues a deposit address for the order. The crypto must be sent from the wallet you gave as walletAddress when creating the order, with the exact amount, on the right network, with the memo or tag if one is given, and before the deposit window closes.

→ See Expiry and incorrect deposits.

Fulfilment flows

How the customer sends the crypto is set on your partner account by Banxa, not per order. Options include a QR code, MetaMask, a redirect back to your wallet app with the deposit details, a WebView bridge, and a custodial flow where your platform sends the crypto and then confirms it via POST /v2/orders/{orderId}/confirm.

→ See Custodial vs. Non-Custodial.