Create transaction
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.
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
/v2/#createTransaction
Request
Header parameters
Requires authentification.
Body parameters
Requires JSON-RPC 2.0 protocol request body.
The params
parameter schema:
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]. |
Sample request payload with refundAddress
and refundExtraId
{
"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>>"
}
}
Sample request payload without refundAddress
and refundExtraId
{
"jsonrpc": "2.0",
"id": "test",
"method": "createTransaction",
"params": {
"from": "eth",
"to": "xrp",
"address": "<<valid xrp address>>",
"extraId": "<<valid xrp extraId>>",
"amountFrom": "0.0339"
}
}
Sample request payload with the userMetadata
{
"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\"}"
}
}
Sample 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>>",
"amountFrom": "0.0339"
}
}'
Response
Response parameters
Requires JSON-RPC 2.0 protocol response body.
The result
parameter 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. |
The result scheme parameter trackUrl
is deprecated. You can retrieve the actual status and transaction data from the getStatus and getTransactions methods.
Sample response with refundAddress
and refundExtraId
{
"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"
}
}
Sample response without refundAddress
and refundExtraId
{
"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"
}
}
Error response
Error response parameters
Check the error response schema.
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. |