{"metadata":{"image":[],"title":"","description":""},"api":{"url":"/v3/swaps","auth":"required","settings":"","results":{"codes":[{"name":"","code":"{\n    \"id\": \"SW_Q6T7W394N78\",\n    \"owner\": \"user:US_BDLD3GBQV2M\",\n    \"status\": \"CREATED\",\n    \"sourceCurrency\": \"BTC\",\n    \"destCurrency\": \"ETH\",\n    \"dest\": \"ethereum:0x6c2605f4B60c965AE59aF0461C876B4Fa46227D7\",\n    \"refundTo\": \"account:AC_YXQ3RHV8LH7\",\n    \"fundingAddress\": \"bitcoin:2ShKJC5uSDe7eCaBkLKsceg4kaJTT3Qau6M\",\n    \"createdAt\": 1620263016000,\n    \"updatedAt\": 1620263016000,\n    \"expiresAt\": 1620522216000,\n    \"swapTransfers\": []\n}","language":"json","status":200},{"name":"","code":"{\n    \"language\": \"en\",\n    \"compositeType\": \"\",\n    \"subType\": \"\",\n    \"exceptionId\": \"live_6Y6GYG\",\n    \"message\": \"Cannot validate ipAddress\",\n    \"type\": \"ValidationException\",\n    \"transient\": false\n}\n\n{\n    \"language\": \"en\",\n    \"compositeType\": \"\",\n    \"subType\": \"\",\n    \"exceptionId\": \"live_3BN6BQ\",\n    \"message\": \"Wyre isn't available in your country. We're always working to expand. Keep checking back to be the first to know when we launch\",\n    \"type\": \"UnsupportedLocationException\",\n    \"transient\": false\n}","language":"json","status":400}]},"params":[{"name":"sourceCurrency","type":"string","default":"","desc":"Specify the crypto currency you'll be sending onto the platform","required":true,"in":"body","ref":"","_id":"606e08bdd514d500125fc543"},{"name":"destCurrency","type":"string","default":"","desc":"This is the target currency to exchange into","required":true,"in":"body","ref":"","_id":"606e08bdd514d500125fc544"},{"name":"dest","type":"string","default":"","desc":"Provide SRN for where to disburse funds after conversion. May identify a blockchain address in the dest currency, wallet, account, or user","required":true,"in":"body","ref":"","_id":"606e08bdd514d500125fc545"},{"name":"refundTo","type":"string","default":"","desc":"Provide SRN for where to disburse funds if conversion fails. May identify a blockchain address in the source currency, wallet, account, or user","required":true,"in":"body","ref":"","_id":"606e08bdd514d500125fc546"},{"name":"notifyUrl","type":"string","default":"","desc":"URL for transfer notification","required":false,"in":"body","ref":"","_id":"606e08bdd514d500125fc547"},{"name":"ipAddress","type":"string","default":"","desc":"IP address. If countryCode is not null, ipAddress is required. When countryCode and ipAddress are both present and if ipAddress is not resolved to the countryCode, it will return HTTP 400 Bad Request.","required":false,"in":"body","ref":"","_id":"609ae371a442a8002ddd9179"}],"examples":{"codes":[{"code":"{\n  \"sourceCurrency\":\"BTC\",\n  \"destCurrency\":\"ETH\",\n  \"dest\":\"ethereum:xxx\",\n  \"refundTo\":\"account:xxx\", // e.g. \"wallet:xxx\",\"account\"xxx\",\"user:xxx\",\"bitcoin:xxx\",\"ethereum:xxx\",\"stellar:xxx\"\n  \"notifyUrl\":\"http://callback.url\",\n  ipAddress: \"x.x.x.x\"\n}","language":"json"}]},"method":"post"},"next":{"description":"","pages":[]},"title":"Create Swap","type":"endpoint","slug":"create-swap","excerpt":"Initiate a transfer without rate locking before your funds have arrived on Wyre","body":"## Create Swap Response\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`id`\",\n    \"1-0\": \"`owner`\",\n    \"13-0\": \"\",\n    \"14-0\": \"`notifyUrl`\",\n    \"h-0\": \"Response Field\",\n    \"h-1\": \"Meaning\",\n    \"0-1\": \"The swap object id.\",\n    \"1-1\": \"The owner of this swap. It will be a user srn.\",\n    \"13-1\": \"\",\n    \"14-1\": \"The data subscription URL which is attached to the subsequently created [transfer](doc:transfer-resources). We will notify this URL of updates to the transfer state with webhooks.\",\n    \"15-0\": \"`refundTxId`\",\n    \"15-1\": \"If the swap is being refunded, this will fill in with the corresponding Wyre transaction ID\",\n    \"16-0\": \"`refundTxNetworkId`\",\n    \"16-1\": \"If the swap is being refunded on the blockchain, this will fill in with the corresponding blockchain network transaction ID\",\n    \"17-0\": \"`refundedAt`\",\n    \"17-1\": \"A milliseconds epoch timestamp when the transfer refund was initiated\",\n    \"6-0\": \"`refundTo`\",\n    \"6-1\": \"\",\n    \"2-0\": \"`status`\",\n    \"2-1\": \"Possible statuses are CREATED, PROCESSING, COMPLETED, EXPIRED, PROCESSING_REFUND, REFUNDED\",\n    \"3-0\": \"`sourceCurrency`\",\n    \"4-0\": \"`destCurrency`\",\n    \"3-1\": \"The funding currency of this swap.\",\n    \"4-1\": \"The exchange currency of this swap.\",\n    \"5-0\": \"`dest`\",\n    \"7-0\": \"`fundingAddress`\",\n    \"7-1\": \"The address generated for this swap. This is where funds should be sent to execute the swap.\",\n    \"8-0\": \"`createdAt`\",\n    \"9-0\": \"`updatedAt`\",\n    \"10-0\": \"`expiresAt`\",\n    \"10-1\": \"A milliseconds epoch timestamp when the transfer will expire which will be 72 hours from its creation time\",\n    \"11-0\": \"`swapTransfers`\",\n    \"11-1\": \"An array of transfer history for this swap.\"\n  },\n  \"cols\": 2,\n  \"rows\": 12\n}\n[/block]\n# Swaps Overview\n\nThe swap API is used to generate a funding address for the swap without specifying the source amount and without the rate locking limitation of a transfer. Normally, transfers have their totals and rates locked upfront; however, the swap API can create defer calculating the total amount until the fund arrives.\n\n## Swap Lifecycle\n\nA newly created swap will be in CREATED status. \n\nWhen fund arrives on the fundingAddress, 2 things could happen.\n\nFor the success path, the swap status will be changed to PROCESSING when a transfer is created. When the fund is confirmed on the network, the status will be changed to COMPLETED.\n\nIn case of the deposit fund is too small and no amount is left for sending the the dest after subtracting all the fees. We will try to refund the deposit amount specify in the refundTo parameter.\nIf the refundTo is a wallet srn, account srn, or user srn. It is not likely to have any refund issue. However, if the refundTo value is a wallet address and in case the error is amount to small, we will refund the funding amount to the swap owner which is the user srn. The status will be changed from `CREATED` to `PROCESSING_REFUND` to `REFUND`.\n\nOnce in `PROCESSING` state, the exchange rate are defined and locked. You could retrieved the swap transfer by calling the get swap endpoint.\n\n## Expiration\n\nAfter a swap has expired, it will cease to function. Funds sent to it will be sent to the refundTo parameter. In case of any error, it will refund to the swap owner which is user srn.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Use Masquerading\",\n  \"body\": \"The endpoint only accept a valid user session. If you are creating a swap on behalf of the user, you will need to use the [masqueradeAs](doc:authentication#masquerading) URL parameter. \\n\\nYou will encounter `AccessDeniedException` responses if you attempt to create a swap  without this.\"\n}\n[/block]","updates":[],"order":8,"isReference":true,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"606e08bdd514d500125fc542","createdAt":"2021-04-07T19:32:13.184Z","user":"54eb8076867e1917009b7160","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Transfers & Exchanges","slug":"transfers","order":7,"from_sync":false,"reference":true,"_id":"5bc633b48f3ff600626e3e18","project":"550f74bb6fc8130d0038aad3","version":"550f75de61d9d30d00af9e01","createdAt":"2018-10-16T18:53:40.959Z","__v":0},"version":{"version":"3","version_clean":"3.0.0","codename":"","is_stable":true,"is_beta":true,"is_hidden":false,"is_deprecated":false,"categories":["550f75de61d9d30d00af9e02","551027e38579861900a86698","551029e08579861900a8669a","551029e7498062190006328a","5bc633a722d682005c9ad9e4","5bc633b08c4b0b000d6a7eaa","5bc633b48f3ff600626e3e18","5bc63538e5a6ba000d22ee6d","5bc63587a18a6b000decd295","5bc635c0937fcb0056223d9c","5bc6360f42f41800319aeaa6","5be5d13ff1d319002baca9ce","5be5d2287cd14d00291fbfdb","5be8b3b09f7cb70023c56a39","5be8b3cbb910100044e20206","5c1d769a4f6aed001fe527f0","5c402942010f0d001496dded","5e8127d61c906800374eeb1c","5f2768c98622b8005106544a","5f2768d05702ca0011f7655e","5f276e5348d2b600321aef9b","5f276fd300e519001139200a","5f9a2cb79dafe500259281a7","5fd92bf362bb7301b00e48ba","60ef489344d5cf002cd7414d"],"_id":"550f75de61d9d30d00af9e01","__v":25,"releaseDate":"2015-03-23T02:09:34.221Z","project":"550f74bb6fc8130d0038aad3","createdAt":"2015-03-23T02:09:34.221Z","forked_from":"550f74bb6fc8130d0038aad6"},"project":"550f74bb6fc8130d0038aad3","__v":21,"parentDoc":null}

postCreate Swap

Initiate a transfer without rate locking before your funds have arrived on Wyre

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Body Params

sourceCurrency:
required
string
Specify the crypto currency you'll be sending onto the platform
destCurrency:
required
string
This is the target currency to exchange into
dest:
required
string
Provide SRN for where to disburse funds after conversion. May identify a blockchain address in the dest currency, wallet, account, or user
refundTo:
required
string
Provide SRN for where to disburse funds if conversion fails. May identify a blockchain address in the source currency, wallet, account, or user
notifyUrl:
string
URL for transfer notification
ipAddress:
string
IP address. If countryCode is not null, ipAddress is required. When countryCode and ipAddress are both present and if ipAddress is not resolved to the countryCode, it will return HTTP 400 Bad Request.

Examples


Result Format


Documentation

## Create Swap Response [block:parameters] { "data": { "0-0": "`id`", "1-0": "`owner`", "13-0": "", "14-0": "`notifyUrl`", "h-0": "Response Field", "h-1": "Meaning", "0-1": "The swap object id.", "1-1": "The owner of this swap. It will be a user srn.", "13-1": "", "14-1": "The data subscription URL which is attached to the subsequently created [transfer](doc:transfer-resources). We will notify this URL of updates to the transfer state with webhooks.", "15-0": "`refundTxId`", "15-1": "If the swap is being refunded, this will fill in with the corresponding Wyre transaction ID", "16-0": "`refundTxNetworkId`", "16-1": "If the swap is being refunded on the blockchain, this will fill in with the corresponding blockchain network transaction ID", "17-0": "`refundedAt`", "17-1": "A milliseconds epoch timestamp when the transfer refund was initiated", "6-0": "`refundTo`", "6-1": "", "2-0": "`status`", "2-1": "Possible statuses are CREATED, PROCESSING, COMPLETED, EXPIRED, PROCESSING_REFUND, REFUNDED", "3-0": "`sourceCurrency`", "4-0": "`destCurrency`", "3-1": "The funding currency of this swap.", "4-1": "The exchange currency of this swap.", "5-0": "`dest`", "7-0": "`fundingAddress`", "7-1": "The address generated for this swap. This is where funds should be sent to execute the swap.", "8-0": "`createdAt`", "9-0": "`updatedAt`", "10-0": "`expiresAt`", "10-1": "A milliseconds epoch timestamp when the transfer will expire which will be 72 hours from its creation time", "11-0": "`swapTransfers`", "11-1": "An array of transfer history for this swap." }, "cols": 2, "rows": 12 } [/block] # Swaps Overview The swap API is used to generate a funding address for the swap without specifying the source amount and without the rate locking limitation of a transfer. Normally, transfers have their totals and rates locked upfront; however, the swap API can create defer calculating the total amount until the fund arrives. ## Swap Lifecycle A newly created swap will be in CREATED status. When fund arrives on the fundingAddress, 2 things could happen. For the success path, the swap status will be changed to PROCESSING when a transfer is created. When the fund is confirmed on the network, the status will be changed to COMPLETED. In case of the deposit fund is too small and no amount is left for sending the the dest after subtracting all the fees. We will try to refund the deposit amount specify in the refundTo parameter. If the refundTo is a wallet srn, account srn, or user srn. It is not likely to have any refund issue. However, if the refundTo value is a wallet address and in case the error is amount to small, we will refund the funding amount to the swap owner which is the user srn. The status will be changed from `CREATED` to `PROCESSING_REFUND` to `REFUND`. Once in `PROCESSING` state, the exchange rate are defined and locked. You could retrieved the swap transfer by calling the get swap endpoint. ## Expiration After a swap has expired, it will cease to function. Funds sent to it will be sent to the refundTo parameter. In case of any error, it will refund to the swap owner which is user srn. [block:callout] { "type": "warning", "title": "Use Masquerading", "body": "The endpoint only accept a valid user session. If you are creating a swap on behalf of the user, you will need to use the [masqueradeAs](doc:authentication#masquerading) URL parameter. \n\nYou will encounter `AccessDeniedException` responses if you attempt to create a swap without this." } [/block]