Create order

Create a crypto sell order and get a redirect URL to the selling page.

HTTP request

post

/v1/sell/orders

Request

Header parameters

Requires authentification.

Body parameters

Name	Type	Required	Description
externalOrderId	string	true	Order ID provided by you.
externalUserId	string	true	User ID provided by you.
providerCode	string	true	The Off-Ramp provider code. Possible values.
currencyFrom	string	true	Ticker of the pay-in currency in uppercase.
currencyTo	string	true	Ticker of the payout currency in uppercase.
amountFrom	number	true	Amount of currency the user is going to pay.
country	string	true	Country ISO 3166-1 code (Alpha-2).
state	string	false	State ISO 3166-2 code. Is required if provided country is US.
ip	string	false	User's IP address.
refundAddress	string	true	Recipient refund address
paymentMethod	string	false	The payment method code. Possible values.
userAgent	string	false	User Agent.
metadata	object	false	Metadata object, which can contain any parameters you need.

Sample payload

application/json

{
  "externalOrderId": "test_user",
  "externalUserId": "test_order",
  "providerCode": "moonpay",
  "currencyFrom": "BTC",
  "currencyTo": "EUR",
  "amountFrom": 0.1,
  "country": "NL"
}

Sample cURL

curl --location --request POST
'https://fiat-api.changelly.com/v1/sell/orders'
--header 'X-Api-Key: {{apiKey}}'
--header 'X-Api-Signature: {{signature}}'
--data-raw '{
  "externalOrderId": "test_user",
  "externalUserId": "test_order",
  "providerCode": "moonpay",
  "currencyFrom": "BTC",
  "currencyTo": "EUR",
  "amountFrom": 0.1,
  "country": "NL"
}'

Response

info

If any of the optional parameters are not provided in the request, they will be returned with the null value in the response.

Response params

Name	Type	Required	Description
redirectUrl	string	true	URL to the provider's selling page.
orderId	string	true	Internal order ID provided by Fiat API.
externalUserId	string	true	User ID provided by you.
externalOrderId	string	true	Order ID provided by you.
providerCode	string	true	The Off-Ramp provider code. Possible values.
currencyFrom	string	true	Ticker of the pay-in currency in uppercase.
currencyTo	string	true	Ticker of the payout currency in uppercase.
amountFrom	string	true	Amount of currency the user is going to pay.
country	string	true	Country ISO 3166-1 code (Alpha-2).
state	string	true	State ISO 3166-2 code. Is required if provided country is US.
ip	string	true	User's IP address.
refundAddress	string	true	Recipient refund address.
paymentMethod	string	true	The payment method code. Possible values
userAgent	string	true	User Agent.
metadata	object	true	Metadata object, which can contain any parameters you need: If you don't provide the metadata object in the request, null will be returned in metadata in response. If you specify an empty object in the request, an empty object will be returned in the response.
createdAt	date-time	true	Time in ISO 8601 format.

Sample response

application/json

{
  "redirectUrl": "https://sell.moonpay.com/changelly?...",
  "orderId": "47430d7d-79f0-4f6d-a738-9d6250f25c9b",
  "externalUserId": "test_user",
  "externalOrderId": "test_order",
  "providerCode": "moonpay",
  "currencyFrom": "BTC",
  "currencyTo": "EUR",
  "amountFrom": "0.1",
  "country": "NL",
  "state": "None",
  "ip": "None",
  "refundAddress": "...",
  "paymentMethod": "sepa_bank_transfer",
  "userAgent": "None",
  "metadata": "None",
  "createdAt": "2025-10-06T11:48:25.557Z"
}

Error response

Error response parameters

Check the error response schema.

Possible error types in the errorType item:

Type	Description
validation	Validation error.
timeout	Request to the provider was not completed in the allotted time.
unavailable	Request failed at the provider's end.
limits	Specified pay-in amount is less than the minimum or more than the maximum value for the fiat currency.
country	Specified country is not supported by the provider.
state	Offer requested for the United States, but the state parameter is not provided.
currency	Specified currency pair is not supported by the provider.
paymentMethod	Specified payment method is not supported by the provider.
invalidOffer	Off-Ramp provider returned an invalid offer.

The errorDetails item schema:

Name	Type	Required	Description
cause	string	true	Error cause. For example, it can equal min or max for the limits error type.
value	string	true	Error value. For example, it can equal the min or max supported value for the limits error type.

Error codes

Code	Message
400	BadRequest
401	Unauthorized
429	TooManyRequests
500	InternalServerError

400

BadRequest

{
  "errorType": "limits",
  "errorMessage": "Limits error",
  "errorDetails": [
    {
      "cause": "min",
      "value": "20"
    }
  ]
}

401

Unauthorized

{
  "errorType": "unauthorized",
  "errorMessage": "Unauthorized",
  "errorDetails": null
}

429

TooManyRequests

{
  "errorType": "tooManyRequests",
  "errorMessage": "Too many requests",
  "errorDetails": null
}

500

InternalServerError

{
  "errorType": "internalServerError",
  "errorMessage": "Internal Server Error",
  "errorDetails": null
}