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
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.
currencyFrom	string	true	Ticker of the payin currency in uppercase.
currencyTo	string	true	Ticker of the payout currency in uppercase.
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.
ip	string	false	User's IP address.
metadata	object	false	Metadata object, which can contain any parameters you need.
paymentMethod	string	false	The payment method code. Possible values.
refundAddress	string	false	Recipient refund address.
userAgent	string	false	User Agent.

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
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.
createdAt	date-time	true	Time in ISO 8601 format.
currencyFrom	string	true	Ticker of the payin currency in uppercase.
currencyTo	string	true	Ticker of the payout currency in uppercase.
externalUserId	string	true	User ID provided by you.
ip	string	true	User's IP address.
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.
orderId	string	true	Internal order ID provided by Fiat API.
externalOrderId	string	true	Order ID provided by you.
paymentMethod	string	true	The payment method code. Possible values
providerCode	string	true	The Off-Ramp provider code. Possible values.
redirectUrl	string	true	URL to the provider's selling page.
refundAddress	string	true	Recipient refund address.
userAgent	string	true	User Agent.

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

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	Bad request
401	Unauthorized
404	Not found
429	Too many requests
500	Internal server error

400

Bad Request

{
  "errorType": "limits",
  "errorMessage": "Too low in amount",
  "errorDetails": [
    {
      "cause": "reason",
      "value": "min"
    },
    {
      "cause": "min",
      "value": "20"
    }
  ]
}

401

Unauthorized

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

404

Not Found

{
  "errorType": "notFound",
  "errorMessage": "Not found",
  "errorDetails": null
}

429

Too Many Requests

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

500

Internal Server Error

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