Create transaction

POST createTransaction

After a successful call of createTransaction method, you get a unique ID to track the transaction status and a payin address for user to send money to.

The method creates a pair of deposit and payout addresses. If somebody sends coins to the same address twice, without the second call to createTransaction, the coins are exchanged and sent to the user's payout address.

note

The amountExpectedTo value should be understood as an expected payout amount to the user before withholding the networkFee. To calculate the exact payout amount, deduct the networkFee value from amountExpectedTo

HTTP request

https://api.changelly.com/v2/#createTransaction

Request

Request

Header parameters

Name	Type	Required	Description
X-Api-Key	string	true	Your API key (SHA256 from Public Key)
X-Api-Signature	string	true	The query's serialized body signed by your private key according to the RSA-SHA256 method.

Body parameters

Name	Type	Required	Description
jsonrpc	string	true	JSON-RPC version.
id	string	true	Client's custom ID.
method	string	true	API method name.
params	object	true	Request parameters.

params object:

Name	Type	Required	Description
from	string	true	Payin currency ticker (in lowercase).
to	string	true	Payout currency ticker (in lowercase).
amountFrom	string	true	Amount of currency that user is going to send.
address	string	true	Recipient address.
extraId	string	false	Additional ID for address for currencies that use additional ID for transaction processing.
refundAddress	string	false	Address of the wallet to refund in case of any technical issues during the exchange. The currency of the wallet must match with the from currency.
refundExtraId	string	false	extraId for refundAddress.
fromAddress	string	false	Address of the wallet from which the user will send payin.
fromExtraId	string	false	extraId for fromAddress.
userMetadata	string	false	Escaped JSON. You can use userMetadata to include any additional parameters for customization purposes. To use this feature, please contact us at [email protected].

Payload

Example 1

application/json

{
  "jsonrpc": "2.0",
  "id": "test",
  "method": "createTransaction",
  "params": {
    "from": "eth",
    "to": "xrp",
    "address": "<<valid xrp address>>",
    "extraId": "<<valid xrp extraId>>",
    "amountFrom": "0.0339"
  }
}

Example 2

application/json

{
  "jsonrpc": "2.0",
  "id": "test",
  "method": "createTransaction",
  "params": {
    "from": "xlm",
    "to": "xrp",
    "address": "<<valid xrp address>>",
    "extraId": "<<valid xrp extraId>>",
    "amountFrom": "400",
    "refundAddress": "<<valid xlm address to make automatic refund in case of transaction fail>>",
    "refundExtraId": "<<valid xlm extraId to make automatic refund in case of transaction fail>>"
  }
}

Example with userMetadata

application/json

{
  "jsonrpc": "2.0",
  "id": "test",
  "method": "createTransaction",
  "params": {
    "from": "eth",
    "to": "xrp",
    "address": "<<valid xrp address>>",
    "extraId": "<<valid xrp extraId>>",
    "amountFrom": "0.0339",
    "userMetadata": "{\"param1\": 50, \"param2\": \"string\", \"param3\": \"50.5189\"}"
  }
}

cURL

curl --location --request POST 'https://api.changelly.com/v2' \
--header 'X-Api-Key: {{apiKey}}' \
--header 'X-Api-Signature: {{sign}}' \
--data-raw '{
  "jsonrpc": "2.0",
  "id": "test",
  "method": "createTransaction",
  "params": {
      "from": "eth",
      "to": "xrp",
      "address": "<<valid xrp address>>",
      "extraId": "<<valid xrp extraId>>",
      "amount": "0.0339"
  }
}'

Response

Example

Sample response

Example 1

application/json

{
  "jsonrpc": "2.0",
  "id": "test",
  "result": {
    "id": "uzul********97b",
    "type": "float",
    "payinExtraId": null,
    "payoutExtraId": "20*****48",
    "amountExpectedFrom": "0.0339",
    "status": "new",
    "currencyFrom": "eth",
    "currencyTo": "xrp",
    "amountExpectedTo": "94.525000",
    "payinAddress": "0x375132b5**********1b36691a72",
    "payoutAddress": "rwpMvfxoo**********WDwQyHUW",
    "createdAt": 1667222297000000,
    "networkFee": "0.22155"
  }
}

Example 2

application/json

{
  "jsonrpc": "2.0",
  "id": "test",
  "result": {
    "id": "uiib******khs9n",
    "type": "float",
    "payinExtraId": "88198*****2666",
    "payoutExtraId": "20*****48",
    "refundAddress": "GAV6LA3M3****************QWQ5LGO365",
    "refundExtraId": "6459********435",
    "amountExpectedFrom": "400",
    "status": "new",
    "currencyFrom": "xlm",
    "currencyTo": "xrp",
    "amountExpectedTo": "100.495000",
    "payinAddress": "GAV6LA3M3OP***********************4HQWQ5LGO365",
    "payoutAddress": "rwpMvfx***************wQyHUW",
    "createdAt": 1667222296000000,
    "networkFee": "0.22155"
  }
}

Success

Response params

Name	Type	Description
jsonrpc	string	JSON-RPC version.
id	string	Client's custom ID.
result	array of objects	Result.

result schema:

Name	Type	Description
id	string	Transaction ID. Could be used in getStatus method.
type	string	Type of transaction. Always float in this method.
payinAddress	string	Address for a user to send coins to.
payinExtraId	string	Extra ID for payinAddress in case it is required. Note: If the payinExtraId parameter is returned in the response and is not null, it is required for user to send the funds to the payinAddress specifying extraId. Otherwise, the transactions will not be processed and the user will need to get a refund through technical support.
payoutAddress	string	Address where the exchange result will be sent to.
payoutExtraId	string	Extra ID for payoutAddress in case it is required.
refundAddress	string	Address of the wallet to refund in case of any technical issues during the exchange. The currency of the wallet must match with the from currency.
refundExtraId	string	Extra ID for refundAddress.
amountExpectedFrom	number	The amountFrom value from createTransaction request.
amountExpectedTo	string	The amountTo value from getExchangeAmount response at the moment of createTransaction. This is the estimated payout amount of currency before withholding the network fee.
status	string	Transaction status. Will always be new when transaction is created. If you reference the same transaction using the getStatus or getTransactions method, you'll get the waiting status as an equivalent to new.
currencyTo	string	Payout currency ticker.
currencyFrom	string	Payin currency ticker.
createdAt	integer	Time in timestamp format (microseconds) when the transaction was created.
networkFee	string	Commission taken by the network from the amount sent to the user. Displayed in pay-out currency.

warning

The result schema parameter trackUrl was deprecated on 06.01.2024.

Errors

Error schema

Name	Type	Description
jsonrpc	string	JSON-RPC version.
id	string	Client's custom ID.
error	object	Possible errors.
»code	integer	Error code.
»message	string	Error message.

Error codes

Code	Message	Description
-32600	Invalid amount: maximal amount is {max_amount}	The attempt to exchange more currency than a maximal amount.
-32600	Invalid amount: minimal amount is {min_amount}	The attempt to exchange less currency than a minimal amount.
-32600	Error: You reached requests limit {limit} rps	You have been sending more than 10 requests per second.
-32602	Invalid currency: {currency} temporary disabled	This currency is currently disabled.
-32602	Invalid currency: {currency} is temporary disabled on API as output currency	This currency is currently disabled on API as an output currency.
-32602	Invalid currency: {currency} is temporary disabled on API as input currency	This currency is currently disabled on API as an input currency.
-32602	Invalid currency: {currency} not found	This currency is not listed on Changelly or the ticker is invalid.
-32602	Parameter {param} is invalid	You've specified an invalid parameter.
-32602	Error: Invalid address	You've specified an invalid payout address.
-32602	Not enough liquidity in pair {from_currency}->{to_currency}. Max amount is {max_from} {from_currency}.	The amount you've specified exceeds maximal volume.
-32603	Internal Error or Error	Most likely, the problem is on our side. Further investigation is required.
-32603	An error encountered during address generation. Please try again later	An error occurred during address generation.