Today, we are excited to announce that Arwen trading is available via API.
Arwen is a non-custodial crypto-to-crypto settlement platform. With Arwen, you can access the liquidity of a centralized exchange without trusting the exchange with custody of your coins. Trades are fast because they happen off blockchain, secure because they are settled via instant atomic swaps, and liquid because they are executed on the exchange’s centralized orderbook. Arwen is currently live for trading at KuCoin, top global exchange.
Let us help you get set up! Drop us a note at support@arwen.io, and we will help set you up to trade programmatically with Arwen! If you’d like to get started on your own, this post has enough information to get you started.
Introducing the Arwen SDK
Arwen is non-custodial settlement layer for trading at a centralized exchange. With Arwen, you can trade without depositing your coins in exchange custody. Instead, your trades are backed by coins that you lock in on-blockchain escrows.
Every Arwen escrow is controlled by two keys — one of which is held by you, the Arwen trader. Your escrow key is securely stored inside the Arwen SDK, a Docker container that you download and and run on your infrastructure. Downloading the Arwen SDK ensures that no one can takes custody of your keys and coins while you trade at a cryptocurrency exchange.
Using the API to interact with the Arwen SDK
You interact with the Arwen SDK’s API in order to place and settle trades with Arwen at a centralized cryptocurrency exchange. To get access to the Docker container, follow the instructions in this open-source GitHub repo. (That is, run the ./download_and_install.sh command!):
https://github.com/cwcrypto/arwen-sdk
This repo also contains arwenlib, a python reference implementation that interacts with Arwen SDK API, parse messages and maintain data structures in memory. You can write your own trading bot on top of arwenlib. The repo also includes several sample scripts that implement a command line interface (CLI) on top of arwenlib. You can get to know arwenlib and the Arwen SDK API by playing with these CLI scripts.
API Docs
API docs for the Arwen SDK are available here:
The Arwen SDK API has three key components: user escrows, exchange escrows, and trades. Here’s how each of them works.
Setting up user escrows by API
What’s a user escrow? When you trade with Arwen, you don’t need to deposit your coins at the exchange. Instead, you lock your coins in an on-blockchain user escrow. (The coin’s native blockchain acts as the agent of escrow; thus, you escrow your bitcoin using a smart contract on the Bitcoin blockchain.) Each user escrow has an expiry time. If the exchange is behaving normally, you will be able to close this escrow at any time, even before it expires. But if the exchange gets hacked or becomes unresponsive, you will be able to close your escrow once the escrow expires. Closing the escrow will release coins back to your wallet.
Setting up the user escrow. This is a two step process.
The first step is to call the endpoint create a user escrow. When you create a user escrow, you specify the amount of coin in escrow, the type of coin in escrow, the expiry time for the escrow, and the exchange at which you want to establish the escrow. (For example, open a user escrow of 5 BTC for 24 hours with KuCoin.) You also need to enter a wallet address where you want to receive coins when your escrow closes. This wallet address is the receiving address of whatever custody solution you use to hold your coins (e.g. hardware wallet, software wallet, third-party custodian.)
The create a user escrow API endpoint will return a user escrow id, and blockchain address for the user escrow.
The second step is to fund your user escrow. To do this, you need to deposit coins in the blockchain address of the user escrow. You deposit coins to this address using whatever wallet solution that you are currently using to hold your coins (e.g. hardware wallet, software wallet, third party custodian, etc.) The API itself is not involved in depositing funds in this escrow — you use your wallet to move these funds!
Setting up exchange escrows via API
What’s an exchange escrow? Once your user escrow is confirmed on the blockchain, you can ask the exchange to fund an exchange escrow for you. The exchange escrow proves that the exchange has sufficient collateral to back coin that you buy on the exchange, and protects you when the exchange becomes unresponsive or hacked.
The exchange escrow is funded by the exchange.
What’s an escrow fee? You pay the exchange an escrow fee when you open an exchange escrow. This compensates the exchange because the exchange is locking up its coins for you. The escrow fee is depends to the number of coins in the exchange escrow, and the expiry time of the exchange escrow. If you close your exchange escrow early, before it expires, you get a rebate of a portion of your escrow fee.
Setting up the exchange escrow. To set up a new exchange escrow, you once again need to specify the amount of coin in escrow, the type of coin in escrow, the expiry time for the escrow, and the exchange at which you want to establish the escrow, as well a wallet address where you want to receive coins when your escrow closes. (For example, open a exchange escrow of 100 ETH for 24 hours with KuCoin.)
You also need to provide information about how you plan to pay for this escrow. You pay the escrow fee for your exchange escrow using a user escrow that you have already opened at the exchange. So, when setting up the new exchange escrow, you must also specify the ID of user escrow from which you will pay your fee.
The exchange will then fund the exchange escrow for you.
Settling Trades by API
To trade at an exchange, you need to pair an user escrow and an exchange escrow. These two escrows should be at the same exchange. (For instance, to sell BTC and buy ETH at KuCoin, you need to pair a BTC user escrow at KuCoin with an ETH exchange escrow at KuCoin.) Multiple trades can be done against a given escrow, and you can pair any user escrow and exchange escrow, as long as they are at the same exchange.
Currently, Arwen trades us an RFQ (“request for quote”) trading instrument.
In an RFQ, you first place an order, specifying the trading pair (“ETH-BTC”), the quantity of ETH you want to buy (“buy 100 ETH”), and ids of the user escrow and exchange escrow that are you are using to execute the trade. The endpoint responds with quote for the amount of BTC that you need to sell (“quote is 0.3 BTC”), and an expiry time indicating how long the quote will be held. This quote is taken from the exchange’s orderbook.
The next step of the RFQ is to execute the order before it expires. (But if you don’t like the quoted price, you can always cancel the order.) Placing the order will execute an instant atomic swap of BTC for ETH. The atomic swap cryptographically ensures that when you transfer you BTC to the exchange, you receive exactly the quoted amount of ETH in return.
Atomic swaps ensure that your coins are never at risk while you trade with Arwen. Your coins are safe, even if the exchange is hacked, goes offline, or loses access to its wallet.
Closing escrows by API
When you are done trading with an escrow, you can close it using the close user escrow or close exchange escrow API endpoints. Arwen ensures that you can close your escrows with the correct balance of coin (reflecting the actual trades you did), even if the exchange goes offline or gets hacked while your escrow is open.
What about KYC?
Currently, Arwen is available on KuCoin, a top global exchange. To trade with Arwen on KuCoin, you first need to complete KYC with KuCoin. Unfortunately, US residents are not currently authorized to trade with Arwen on KuCoin.
Next, you must call the Authorize Arwen via OAuth API endpoint on the Arwen SDK. This endpoint will respond with a URL. You then visit that URL and follow the instructions need to authorize Arwen to learn whether you have completed KYC (or not).
Get some practice on testnet.
If you want to try out your bot, or you can’t complete KYC on KuCoin, you can always use the Arwen SDK to trade testnet coins. We’ve provided two different startup scripts — one script starts the Arwen SDK in mainnet mode, while the other starts the Arwen SDK in testnet mode.
See here for info about obtaining a wallet the supports testnet and coins from a testnet faucet.
Let us help you get set up!
Drop us a note at support@arwen.io if you’d like some help getting set up to trade programmatically with Arwen!
We’ve also set up a playground virtual machine that will allow you to interact with the Arwen SDK via arwenlib and the sample scripts implementing a CLI on top of arwenlib. Contact us at support@arwen.io and we can get access to the playground. We look forward to hearing from you!
