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.

info

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

post/v2/#createTransaction

Request

Header parameters

Requires authentication.

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

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>>"
  }
}

Sample request payload without refundAddress and refundExtraId

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"
  }
}

Sample request payload with the 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\"}"
  }
}

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	Additional 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	Additional 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	Additional 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 payout currency.

warning

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

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"
  }
}

Sample response without refundAddress and refundExtraId

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"
  }
}

Error response

Error response parameters

Check the error response schema.

Error codes

Code	Message	Description
`-32601`	`Method not found`	The method you're calling doesn't exist.
`-32602`	`Invalid amount for pair {from_currency}->{to_currency}`	The attempt to exchange more currency than a maximal amount or less than the minimal one.
`-32602`	`Invalid amount for pair {from_currency}->{to_currency}. {limit_type} amount is {limit} {currency}`	The attempt to exchange currency out of limits. `{limit_type}` is a “Minimal“ or “Maximum“ value.
`-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`	`Invalid pair: {from_currency}->{to_currency} not available or temporary disabled`	This currency pair is not listed on Changelly or the currency pair 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`	`Error: You reached requests limit {limit} rps`	You have sent requests more than the RPS limit. The default RPS limit is 10.
`-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.

Create transaction

HTTP request​

Request​

Header parameters​

Body parameters​

Response​

Response parameters​

Error response​

Error response parameters​

Error codes​