Arwen Client · Apiary

{"mock":"https://private-anon-dd5211c2ae-arwenclient.apiary-mock.com/:DockerPort/api/v1/","production":"http://localhost/:DockerPort/api/v1/","proxy":"https://private-anon-dd5211c2ae-arwenclient.apiary-proxy.com/:DockerPort/api/v1/"}

FORMAT: 1A HOST: http://localhost:DockerPort/api/v1 # Arwen Client Repo: https://github.com/cwcrypto/tradeBot ### At a glance This document outlines the proposed Arwen Client targeted towards more technical users that wish to trade using the Arwen Protocol against supported exchanges. ### Key Differences from Traditional Exchange APIs: The Arwen Protocol enables non-custodial cryptocurrency trading. To accomplish this a set of User and Exchange Escrows must be open in order to trade. The burden of opening User escrows and requesting Exchange escrows to be opened falls on the User. The Arwen Client aims to streamline this process as much as possible. We have taken note about how traditional cryptocurrency exchanges operate a trading API and have tried to simulate the trading flow as much as possible while providing a secure non-custodial trading solution. Users will notice new types of endpoints that deal with User Escrows and Exchange Escrows. #### Important Note About BUY and SELL within Arwen Although the Arwen protocol does define how to both Buy and Sell coin between a User and Exchange Escrow, the functionality has not yet been implemented. Currently Arwen only supports _unidirectional_ escrow transfers - from User to Exchange Escrow only - which means that BUY and SELL within the Arwen Client more accurately reflect how an Exchange treats Buys and Sells within a given Base-Quote pair (i.e BTCLTC).   Symbols should always be in "ExchangeCurrency-UserCurrecny" format. ## Trading Flow: - User launches a docker container that will initialize Arwen Client - User asks Arwen Client to open User Escrows for each cryptocurrency they want to sell - User funds User Escrows from a hot wallet under User’s control - User asks ArwenClient to open Exchange Escrows for each cryptocurrency they want to buy and designates a return address where funds will be sent upon Exchange Escrow close - User approves Exchange Escrow fees though Arwen Client and then the Exchange will open the Exchange Escrows - User polls for RFQ prices from the Arwen Client - User selects a quote-base pair of cryptocurrencies and asks Arwen Client for RFQ order price quote - User is returned a time-frame in which to request execution of RFQ trade - User tells Arwen Client to execute RFQ trade and waits for confirmation or rejection - User can also cancel RFQ trade before expiration time - When User is done trading they should close User and Exchange Escrows. As a precaution Arwen Client will close escrows automatically when they are due to expire - User queries Arwen Client for information on User and Exchange Escrows to determine when the Escrows are closed ## Technical Details - Interaction with Arwen Client is handled by an API using HTTP requests with json objects - Deployed using [Docker](https://www.docker.com) container - The API is unauthenticated - Arwen Client is not a wallet, the user must have prepared addresses for supported currencies - User escrow keys for closing escrows are managed by Arwen - Arwen Client adheres to Arwen Protocol security procedures ## KYC To use the Arwen app, users must first KYC with each exchange on thier own. After the user has successfully KYC'd with the exchange, she must either register their API keys with Arwen Client or perform OAuth within thier browser sfgsdfgs. ### KuCoin OAuth The following only needs to be preformed once: - Start the Arwen Client docker container - Initialize your session with Arwen Client with the Init endpont (detialed below) - Request your unique OAuth url from the KYC-OAuth endpoint (detialed below) - Copy-paste the url into your browser and follow the steps provided by KuCoin - Arwen and Kucoin perform the rest of the OAuth process after this point, no information needs to be returned to Arwen Client, you may being trading at this point ### Testnet Exchanges and Api Key Registration All testnet excahnges use the same testnet API key and secret for now. They can be found in the tradeBot repo Testnet exchange names (case senstaive): - Binonce - Tracken - Coinboss - Roloniex - Bitfinesse Mainnet exchanges (case sensative): - kucoinrfq ## Notes: - All timestamps are in **seconds** - All prices and quantities are represented as **strings** - 200 means successful request - 4XX errors are user caused and should be treated as a failed message - 5XX errors are internal server errors and should not necessarily be treated as a failure - Data is always returned **oldest first** - Escrow States: - OPENING - OPEN - TRADING - CLOSED - UNKOWN - Order States: - OPEN - EXECUTED - CANCELLED - EXPIRED - UNKOWN For support please email `support@arwen.io` with subject `[Arwen Client]` or open an issue at `https://github.com/cwcrypto/tradeBot` # Group Account Management ## Start Client [/init] You must log in everytime you restart the docker contrainer. The first time you hit this endpoint it will return the hdseed. Afterwards, "Signed In" will be returned to indicate that your session has been initialized. ### Init (Key Generation and Sign In) [POST] + Response 200 (application/json) { "hdseed": "12 word hdseed" } ## Ping [/ping] ### Ping Arwen Client API [GET] + Response 200 (text) "pong" ## Time [/time] ### Retrieve Arwen Client's time [GET] + Response 200 (json/application) { "time": 1562776183 // System clock time of the docker } ## Register Exchange API Keys [/kyc/register] ### Authorize Arwen via API Keys [POST] + Request (json/application) { "exchId": "Binonce", "apiKey": "", "apiSecret": "" } + Response 200 (json/application) { "status": true } ## Register Exchange OAuth [/kyc/oauth] ### Authorize Arwen via OAuth [POST] + Request (json/application) { "exchId": "Binonce" } + Response 200 (json/application) { "oauthUrl": "https://passport.kucoin.com/direct?userId={USERID}&exchId={EXCHID}&clientId=Arwen" } ## KYC Status [/kyc/status] ### Authorize Arwen via OAuth [POST] + Request (json/application) { "exchId": "kucoinrfq" } + Response 200 (json/application) { "exchId": "kucoinrfq", "kycStatus": "PROCESSED" } ## Exchanges [/exchanges] UNDER DEVELOPMENT - does work, the json is just massive at the moment. ### List Exchanges, currencies, and limits [GET] + Response 200 (application/json) {'limits': {'BCH': {'EXCHANGE': { 'maxEscrowAmount': 300000000, 'maxEscrowLength': 604800, 'maxTradeAmount': 150000000, 'minEscrowAmount': 3500000, 'minEscrowLength': 86400, 'minTradeAmount': 200000}, 'USER': { 'maxEscrowAmount': 300000000, 'maxEscrowLength': 604800, 'maxTradeAmount': 150000000, 'minEscrowAmount': 3500000, 'minEscrowLength': 86400, 'minTradeAmount': 200000}}, 'BTC': {'EXCHANGE': {'maxEscrowAmount': 10000000, 'maxEscrowLength': 604800, 'maxTradeAmount': 5000000, 'minEscrowAmount': 210000, 'minEscrowLength': 86400, 'minTradeAmount': 4000}, 'USER': {'maxEscrowAmount': 10000000, 'maxEscrowLength': 604800, 'maxTradeAmount': 5000000, 'minEscrowAmount': 210000, 'minEscrowLength': 86400, 'minTradeAmount': 4000}}, 'LTC': {'EXCHANGE': {'maxEscrowAmount': 900000000, 'maxEscrowLength': 604800, 'maxTradeAmount': 500000000, 'minEscrowAmount': 7000000, 'minEscrowLength': 86400, 'minTradeAmount': 1000000}, 'USER': {'maxEscrowAmount': 900000000, 'maxEscrowLength': 604800, 'maxTradeAmount': 500000000, 'minEscrowAmount': 7000000, 'minEscrowLength': 86400, 'minTradeAmount': 1000000}}}, 'supportedBlockchains': ['BTC', 'BCH', 'LTC'] } ## Fee History [/feehistory] Returned in order from oldest first ### Get all fees paid for opening exchange escrows [GET] + Request (application/json) { "fromTime": 1562776183 } + Response 200 (application/json) [ { "userEscrowId": "901", "userEscrowCurrency": "BTC", "userEscrowQty": 0.0001000, "exchId" : "Binonce", "exchEscrowId": "304", "timePaid": 1562776183 } ] # Group User Escrow Management ## User Escrow Details [/userescrow/query] ### Query for User Escrows [POST] + Request (application/json) { "id": null, // If userEscrowId is set, all other filters are ignored "fromTime": 1562776183, "limit": 1000, // defualt is to return all "exchId": "Binonce", // defualt is all exchanges "isFinal": false // boolean, defualt is false } + Response 200 (application/json) [ { "exchId": "Binonce", "userEscrowId": "304", "escrowAddress": "0x...", "state": "OPEN", "amount": 5.00000000, "availableToTrade": 2.84750000, "userEscrowCurrency": "BTC", "trades": [ "1337" ], "amountSentToReserve": -1, "timeCreated": 1562776183, "timeClosed": -1 } ] ## Create a User Escrow [/userescrow/create] ### New User Escrow (unfunded) [POST] + Request (application/json) { "exchId": "Binonce", "userEscrowCurrecny": "BTC", "amount": 5.00000000, "reserveAddress": "0x...", // Where to send your coin after escrow clsoes "expiryTime": 1562776175 // Defualt minimum is 24 hours } + Response 200 (application/json) { "userEscrowId": "304", "escrowAddress": "0x...", "amountToFund": 5.00312000 } ## Close a User Escrow [/userescrow/close] If a new user escrow was created but not funded, then Arwen Client will cancel it (no on chain interactions). If a user escrow was funded then Arwen Client will try to close the escrow according to the state it is in. ### Close/cancel a user escrow [POST] + Request (application/json) { "userEscrowId": "304" } + Response 200 (application/json) { "close": true // boolean } ## User Escrow Cleanup [/cleanup] In the situation an escrow was partially funded or opened but never funded you will want to close those escrows in order to retrieve the funds locked up. This endpoint can be called regularly or when the user believes there are mal-formed user escrows to signal to the Arwen Client to scan for stale escrows. Arwen Client will then generate transactions to refund to reserve address for malformed escrows. If there is nothing to clean up an empty list is returned. ### Cleanup [POST] + Response 200 (application/json) { [ "304" ] } # Group Exchange Escrow Management ## Exchange Escrow Details [/exchescrow/query] ### Query for Exchange Escrows [POST] + Request (application/json) { "id": null, // If exchEscrowId is set, all other filters are ignored "fromTime": 1562776183, "limit": 1000, // defualt is to return all "exchId": "kucoinrfq", // defualt is all exchanges "isFinal": false, // boolean, defualt is false } + Response 200 (application/json) [ { "exchId": "Binonce", "exchEscrowId": "304", "escrowAddress": "0x...", "state": "OPEN", "amount": 5.00000000, "availableToTrade": 2.84750000, // -1 if closed "exchEscrowCurrency": "BTC", "trades": [ "1337" ], "amountSentToReserve": -1, // -1 until closed "timeCreated": 1562776183, "timeClosed": -1 } ] ## Price an Exchange Escrow [/exchescrow/price] ### Request a price (no commitment) [POST] + Request (application/json) { "exchId": "Binonce", "exchCurrency": "BTC", "amount": 5.00000000, "expiryTime": 1562776183, // defualt is 1 day "userCurrency": [ "BTC", "LTC" ] } + Response 200 (application/json) [ { "currency": "BTC", "amount": "0.00034560" } { "currency": "LTC", "amount": "0.00200000" } ] ## New Exchange Escrow [/exchescrow/create] ### Request new Exchange Escrow (funded by exchange) [POST] + Request (application/json) { "exchId": "kucoinrfq", "exchCurrency": "LTC", "qty": "10.00000000", "expiryTime": null, // defualt time is 24 hours "userCurrency": "BTC", "userEscrowId": "304", "maxPrice": "0.00050000" "reserveAddress": "0x..." // where to send your funds to } + Response 200 (application/json) { "exchEscrowId": "901", "escrowAddress": "0x...", "pricePaid": "0.00034560", // May be less than maxProce } ## Close an Exchange Escrow [/exchescrow/close] ### Close an Exchange Escrow [POST] + Request (application/json) { "exchEscrowId": "304" } + Response 200 (application/json) { "closed": true } # Group Trading ## Order Details [/orders/query] ### Get a list of orders filtered by time and exchange [POST] + Request (application/json) { "orderId": null, // If orderId is set, all other filters are ignored "fromTime": "1562776183", "limit": 1000, // defualt is to return all "exchId": "kucoinrfq", // defualt is all exchanges "isFinal": "false", // defualt is false } + Response 200 (application/json) [ { "orderId": "1337", "type": "RFQ", "state": "EXECUTED", // CANCELED, EXPIRED "symbol": "BTC-LTC", // Exchange-User "price": null, // when limit orders are released "userEscrowQty": "0.001", "exchEscrowQty": "0.1", "side": "BUY", "userEscrowId": "304", "exchEscrowId": "901", "timeCreated": "", // When the order was created "timeClosed": "" // When the action was taken (executed, canceled, expired) } ] ## Inquire Price [/orders/inquiry] Note: you need a user and exchange escrow open for RFQ pricing ### Get current price from RFQ pricer [POST] + Request (application/json) { "qty": "0.03000000", "side": "BUY", "userEscrowId": "304", "exchEscrowId": "901" } + Response 200 (application/json) { "buyCurrecny": "LTC", "sellCurrency": "BTC", "buyQty": "0.03000000", "sellQty": "0.30000000" } ## Place an Order [/orders/quote] ### Submit an Order [POST] + Request (application/json) { "type": "RFQ", "symbol": "BTC-LTC", "timeInForce": "FOK", "price": null, // for RFQ this does not matter "qty": "0.03000000", "side": "BUY", "userEscrowId": "304", "exchEscrowId": "901" } + Response 200 (applciation/json) { "userEscrowId": "304", "exchEscrowId": "901", "orderId": "1337", "buyCurrecny": "LTC", "sellCurrecny": "BTC", "price": null, // for RFQ this does not matter "buyQty": "0.03000000", "sellQty": "0.00300000", "quoteExpiry": "1562776183" // 30 seconds from time of request } ## Execute Order [/orders/exectute] ### Execute [POST] + Request (application/json) { "orderId": "1337" } + Response 200 (application/json) { "executed": true } ## Cancel Order [/orders/cancel] ### Cancel [POST] + Request (application/json) { "orderId": "1337" } + Response 200 (application/json) { "canceled": true }