{"swagger":"2.0","info":{"description":"Welcome to DutchX API docs (read-only).\n\nOn this interface you may query various information about tokens, markets,\nauction states, accounts of the **DutchX** protocol.\n\nAll endpoints are returned to you by reading the states directly off the\nEthereum blockchain from the\n[following smart contracts](https://dutchx.readthedocs.io/en/latest/smart-contracts_addresses.html).\n\nWe provide you with the `TRY` button, such that the different endpoints can\nbe tested from the documentation web itself.\n\nFor all available information, please check the [Documentation](https://dutchx.readthedocs.io/en/latest/)","version":"1.0","title":"DutchX API","termsOfService":"https://dutch.d.exchange/terms/","contact":{"name":"DutchX Gitter channel","url":"https://gitter.im/gnosis/DutchX"},"license":{"name":"MIT License","url":"https://github.com/gnosis/dx-services/blob/master/LICENSE.md"}},"basePath":"/api/v1","tags":[{"name":"Markets and supported tokens","description":"Get market info"},{"name":"Prices","description":"Get prices info"},{"name":"Auction state","description":"Get general auctions info"},{"name":"Auction volumes","description":"Get auctions volume info"},{"name":"Accounts information","description":"Get account data"}],"externalDocs":{"description":"Find out more about our exchange","url":"https://dutch.d.exchange"},"paths":{"/tokens":{"get":{"tags":["Markets and supported tokens"],"summary":"Available tokens","description":"Returns an array of **all tokens that are listed** on the DutchX. (beware: if a not ERC20 token is listed; wrongly added tokens cannot be traded)\n\nAll tokens are, at least, listed in an auction with WETH.\n\nCheck “Availible markets” for a list of those that are tradable.\n\nFor information on how to list a token pair: [https://dutchx.readthedocs.io/en/latest/add-token-to-trade.html](https://dutchx.readthedocs.io/en/latest/add-token-to-trade.html)","operationId":"getTokens","produces":["application/json"],"responses":{"200":{"description":"successful operation","schema":{"required":["data","pagination"],"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/definitions/TokenDetails"}},"pagination":{"$ref":"#/definitions/PaginationObject"}}}}}}},"/tokens/whitelisted":{"get":{"tags":["Markets and supported tokens"],"summary":"Whitelisted tokens","description":"Returns **all tokens that have been whitelisted** on the DutchX protocol.\n\nA whitelisted token has the potential to create Magnolia tokens (used for reduction of liquidity contribution) if traded in a whitelisted pair.\n\nTokens can be available for trading on the DutchX protocol, albeit not whitelisted (and hence trades do not generate Magnolia); on the flip side, tokens could be whitelisted, however not listed/traded on the DutchX protocol.\n\nCheck “Availible markets” for a list of those that are tradable.\n\nFor information on how to list a token pair: [https://dutchx.readthedocs.io/en/latest/add-token-to-trade.html](https://dutchx.readthedocs.io/en/latest/add-token-to-trade.html)","operationId":"getWhitelistedTokens","produces":["application/json"],"responses":{"200":{"description":"successful operation","schema":{"required":["data","pagination"],"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/definitions/TokenDetails"}},"pagination":{"$ref":"#/definitions/PaginationObject"}}}}}}},"/markets":{"get":{"tags":["Markets and supported tokens"],"summary":"Available markets (token pairs)","description":"Returns an array of all the available markets (auctions) in the DutchX. (beware: if a not ERC20 token is listed; wrongly added tokens cannot be traded)\n\nNote that each available token pairing always runs the two opposite auctions simultaneously.\n\nFor information on how to list a token pair: [https://dutchx.readthedocs.io/en/latest/add-token-to-trade.html](https://dutchx.readthedocs.io/en/latest/add-token-to-trade.html)","operationId":"getMarkets","produces":["application/json"],"responses":{"200":{"description":"successful operation","schema":{"required":["data","pagination"],"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/definitions/TokenPair"}},"pagination":{"$ref":"#/definitions/PaginationObject"}}}}}}},"/markets/{tokenPair}/is-valid-token-pair":{"get":{"tags":["Markets and supported tokens"],"summary":"Check if market exists","description":"Check if a given token pair has been listed in the DutchX protocol.\n\nReturns `true` only if the token pair has been added\n\nFor information on how to list a token pair: [https://dutchx.readthedocs.io/en/latest/add-token-to-trade.html](https://dutchx.readthedocs.io/en/latest/add-token-to-trade.html)","operationId":"isValidTokenPair","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"type":"boolean"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/markets/{tokenPair}/state":{"get":{"tags":["Auction state"],"summary":"General market state","description":"Returns the current state of the requested market.\n\n\nThe result will be the general market state for the market, so it will be\nrefering to both of the concurrent auctions: A-B and B-A\n\n\nIt can be one of the following values:\n- `RUNNING` - Both auctions are currently ongoing.\n- `WAITING_FOR_FUNDING` - Sell volume has not reached the threshold to start\n- `WAITING_FOR_AUCTION_TO_START` - Sell volume threshold was reached and auction should start in next 10 minutes\n- `ONE_AUCTION_HAS_CLOSED` - One of the auctions it's running, the other is already closed\n- `PENDING_CLOSE_THEORETICAL` - All the sell volume has been bought, so\n  the auction is closed, and the price is determined.\n  However **it's not officially closed until the clearing process is done**.\n  Since DutchX protocol is running in the blockchain, someone\n  has to trigger the clearing by executing a sell order, buy order or claim action\n  to do the clearing.\n\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getMarketState","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"type":"string","enum":["RUNNING","WAITING_FOR_FUNDING"]}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/markets/{tokenPair}/state-details":{"get":{"tags":["Auction state"],"summary":"Market state details","description":"Returns the current state details of the requested market.\n\nAditionally, it includes information about both sides of the current auction,\nso for a token `A-B`, it will include the details for auction `A-B`\n(`auction` property) and `B-A` (`auctionOpp` property).\n\nThe `state` can be one of the following values:\n- `RUNNING` - Both auctions are currently ongoing.\n- `WAITING_FOR_FUNDING` - Sell volume has not reached the threshold to start\n- `WAITING_FOR_AUCTION_TO_START` - Sell volume threshold was reached and auction should start in next 10 minutes\n- `ONE_AUCTION_HAS_CLOSED` - One of the auctions it's running, the other is already closed\n- `PENDING_CLOSE_THEORETICAL` - All the sell volume has been bought, so\n  the auction is closed, and the price is determined.\n  However **it's not officially closed until the clearing process is done**.\n  Since DutchX protocol is running in the blockchain, someone\n  has to trigger the clearing by executing a sell order, buy order or claim action\n  to do the clearing.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getMarketDetails","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/MarketState"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/markets/{tokenPair}/current-index":{"get":{"tags":["Auction state"],"summary":"Current auction index","description":"Returns the current auction index.\n\nUpon listing and trading, the token pair started at auction index `1`. All subsequent auctions are numbered.\n\nThere is always only at most one auction running at the same time per token pair.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getAuctionIndex","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"type":"integer","format":"int64"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/markets/{tokenPair}/auction-start":{"get":{"tags":["Auction state"],"summary":"Current auction start","description":"Returns the date and time when the auction started, or if the auction it's in `WAITING_FOR_AUCTION_TO_START` state, it's the starting time.\n\nThe date is in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getAuctionStart","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"type":"string","format":"date-time"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/markets/{tokenPair}/prices/running":{"get":{"tags":["Prices"],"summary":"Running auction price","description":"Current auction's bid price.\n\nThis price **starts high** (double the closing price of the previous auction), and then **decreases over time**.\n\nIt'll take exactly **6 hours** to decrease the price until the prior closing price. This is why auctions usually last arround 6 hours.\n\nIf an auction is shorter than 6 hours, it means that it closed with a higher price (price increment).\n\nIf an auction closes after more than 6 hours, means that it closed with a smaller price (price decrement),\n\nThe price function **will reach `0` after `24h`** if no bidder buys the auction.\n\nThe price function is the following one:\n\n`P(t) = CP * (24 - t) / ( 12 + t)`\n\nWhere:\n* `t`: Time in hours\n* `CP`: Last closing price\n\nThis is the price that bidders are guaranteed when they send their buy order. However, since the price keeps decreasing, they will end up paying only the closing price.\n\nIt's up to the bidder if he wants to claim right away, or he wants to wait until the auction is over (so he can claim the full amount).\n\nSomething important about this price, is that **it's not symetrical**. At the begining of the auction, both are double the closing price. The only time when this price is symetrical, it's exactly after 6 hours, because it's when the prices meet.\n\nUsually, both auctions run at the same time, but, if the auction hasn't started in 24h, and there's no liquidity on one of the sides, it can run with only one side. In this extraordinary case, you will get only a price in the running auction's side. The other side will return `null`.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getCurrentPrice","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/MarketPrice"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/markets/{tokenPair}/prices/closing":{"get":{"tags":["Prices"],"summary":"Last closing prices","description":"Returns a list of the latest closing prices for a given market.\n\nYou may select how many past auctions you would like to view (`count`).\n\nYou can find the auction index as well as the price increments (in %-change to the last closing price).\n\nThe price A-B is read `1 A gave [value] B`.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getLastClosingPrices","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"},{"name":"count","in":"query","type":"integer","format":"int32","minimum":1,"maximum":50,"default":10,"required":false,"description":"The number of markets to query from last"}],"responses":{"200":{"description":"successful operation","schema":{"type":"array","items":{"type":"object","required":["auctionIndex","price"],"properties":{"auctionIndex":{"type":"integer","format":"int32"},"priceIcrement":{"type":"number"},"price":{"$ref":"#/definitions/MarketPrice"}}}}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/markets/{tokenPair}/prices/closing/{auctionIndex}":{"get":{"tags":["Prices"],"summary":"Closing price for auction","description":"Returns a specific closing price for a certain `auctionIndex`.\n\nThe price A-B is read `1 A gave [value] B`.\n\nTo see which index the auction is currently at, check the endpoint \"Auction State > Current auction index\"\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getClosingPrice","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"},{"name":"auctionIndex","in":"path","description":"Auction index","required":true,"type":"integer","format":"int64"}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/MarketPrice"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/markets/{tokenAddress}-WETH/prices/simple-median":{"get":{"tags":["Prices"],"summary":"Simple median price","description":"Returns the median of the closing prices for a given token.\n\nAll prices are given in Ether.\n\nThe median has proven to be more resistant to market manipulation. Check here for more information about the [median](https://en.wikipedia.org/wiki/Median).\n\nYou can optionally specify the auction index of the auction (`auctionIndex`), and then the number of auctions to consider in the median (`numberOfAuctions`).\n\nIf you don't specify the auction index, the current auction index will be used instead.\n\nIf there's not enough auctions to calculate the median it returns `null`.\n\n**Important: the contract is only safe for odd numbers of auctions. See [here](https://github.com/gnosis/dx-price-oracle/blob/master/contracts/DutchXPriceOracle.sol#L165).**\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getOraclePriceSimpleMedian","produces":["application/json"],"parameters":[{"name":"tokenAddress","in":"path","description":"A token address string for selecting the desired token","required":true,"type":"string"},{"name":"auctionIndex","in":"query","description":"The auction index to start calculating the median."},{"name":"numberOfAuctions","in":"query","type":"integer","format":"int32","minimum":1,"maximum":61,"default":9,"required":false,"description":"Number of auctions to consider. **Contract is only safe for odd numbers of auctions. See [here](https://github.com/gnosis/dx-price-oracle/blob/master/contracts/DutchXPriceOracle.sol#L165).**"}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/MarketPrice"}},"404":{"description":"The token provided is not found"}}}},"/markets/{tokenAddress}-WETH/prices/safe-median":{"get":{"tags":["Prices"],"summary":"Safe median price","description":"Returns, for a given token, the **Ether price** of that token, as the **safe median of last 9 auctions**.\n\nThe \"safe\" part, just means that, it **only returns a price if the following restrictions are accomplished**:\n* **9 auctions have run consecutively** (i.e. if enough liquidity was given). It requires to have at least 9 auctions cleared in the last 4.5 days.\n* **The token is whitelisted**\n\nIf no safe median price is available, it returns `null`.\n\nThis endpoint just reads from the following Oracle: https://github.com/gnosis/dx-price-oracle\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getOraclePrice","produces":["application/json"],"parameters":[{"name":"tokenAddress","in":"path","description":"A token address string for selecting the desired token","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/MarketPrice"}},"404":{"description":"The token provided is not found"}}}},"/markets/{tokenAddress}-WETH/prices/custom-median":{"get":{"tags":["Prices"],"summary":"Custom median price","description":"Returns, for a given token, the **Ether price** of that token, as the **median of the specified number of auctions**. In adition to the token and the number of auction you can specify:\n* **time**: A date string to check the oracle price in a past time using [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format. If no time selected it will check current time.\n* **requireWhitelisted**: if you require to check if the token have been whitelisted in the DutchX. By default is `true`.\n* **maximumTimePeriod**: The maximum time lapse between the first and the last auction. By default is `388800` this is `4.5` days in seconds. The minimum value is '1' second and the maximum value is `1296000`, equivalent to `15` days in seconds\n\nIf it's not possible to get a price meeting the requirements, it will return `null`.\n\n**Important: the contract is only safe for odd numbers of auctions. See [here](https://github.com/gnosis/dx-price-oracle/blob/master/contracts/DutchXPriceOracle.sol#L165).**\nThis endpoint just reads from the following Oracle: https://github.com/gnosis/dx-price-oracle\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getOraclePriceCustom","produces":["application/json"],"parameters":[{"name":"tokenAddress","in":"path","description":"A token address string for selecting the desired token","required":true,"type":"string"},{"name":"time","in":"query","description":"A date string using [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format.\n\nex: *'2018-07-02', 'YYYY-MM-DD'*","required":false,"type":"string"},{"name":"requireWhitelisted","in":"query","description":"Require the token to be whitelisted on the DutchX","required":false,"type":"boolean","default":true},{"name":"maximumTimePeriod","in":"query","description":"Maximum time period between clearing time of last auction and `time`","required":false,"type":"integer","format":"int32","minimum":1,"maximum":1296000,"default":388800},{"name":"numberOfAuctions","in":"query","type":"integer","format":"int32","minimum":1,"maximum":61,"default":9,"required":false,"description":"Number of auctions to consider. **Contract is only safe for odd numbers of auctions. See [here](https://github.com/gnosis/dx-price-oracle/blob/master/contracts/DutchXPriceOracle.sol#L165).**"}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/MarketPrice"}},"404":{"description":"The token provided is not found"},"412":{"description":"<span class=\"markdown\">\n  INVALID_MAXIMUM_TIME_PERIOD:\n  <ul>\n    <li>`maximumTimePeriod` value is not between 1 and\n    1296000, the equivalent to 2 weeks in seconds.</li>\n  </ul>\n  INVALID_NUMBER_OF_AUCTIONS:\n  <ul><li>`numberOfAuctions` value isn't between 1 and 61,\n  the equivalent to 2 weeks of auctions running continously + 1 to make it odd as required by contract.</li></ul>\n  DATE_FORMAT:\n  <ul><li>Invalid date format. The required format is a valid [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format</li></ul>\n</span>"}}}},"/markets/{tokenPair}/extra-tokens/{auctionIndex}":{"get":{"tags":["Auction volumes"],"summary":"Liquidity Contributions","description":"Extra tokens - **Liquidity Contributions** (**LC**) - that will be batched for next auction\n\n**Every ask and bid in the DutchX is subjected to a LC**, that means, that a small percentage of the amount would be deducted from the order and it will be added as liquidity for next auction.\n\nThe LC **will be given to the bidders** on top of the tokens they are entitled by the closing price, so it's good for:\n* **Bidders**: They get more tokens, on top of the ones they bought.\n* **Sellers**: Since the bidders have this incentive, the auction will clear earlier, raising the price a bit, and giving sellers a better price.\n\nNote, that you have to include the auction index (`auctionIndex`).\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getExtraTokens","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"},{"name":"auctionIndex","in":"path","description":"Auction index","required":true,"type":"integer","format":"int64"}],"responses":{"200":{"description":"successful operation","schema":{"type":"number"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/markets/{tokenPair}/sell-volume":{"get":{"tags":["Auction volumes"],"summary":"Current sell volume","description":"Returns the sell volume for the running auction.\n\nIt will return:\n* **The sell volume**: Only if the auction is currently running.\n* **null**: In any other case\n\nIt's important to note, that once an auction starts, **the sell volume won't change during the auction**.\n\nThe auction will clear when the buy volume equals the sell volume at the current price.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getSellVolumeForCurrentAuction","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"type":"number"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/markets/{tokenPair}/sell-volume-next":{"get":{"tags":["Auction volumes"],"summary":"Next sell volume","description":"Returns the sell volume for the next auction.\n\nAlthougt **a seller can post a sell order anytime**, the protocol **won't allow to sell on an a running auction**, this is why, they will deposit the tokens of the bid order into the next auction.\n\nOnce the current auction is cleared, and only if there's enough sell liquidity (`1000$` worth of the token), the **next auction will be scheduled to start in 10 min**.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getSellVolumeNext","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"type":"number"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAADdress}-{tokenBAddress}"}}}},"/markets/{tokenPair}/buy-volume":{"get":{"tags":["Auction volumes"],"summary":"Current buy volume","description":"Returns the buy volume for the running auction.\n\nIt will return:\n* **The buy volume**: Only if the auction hasn'r cleared yet.\n* **null**: In any other case\n\nIt's important to note, that the buy volume starts `0`, and then it's incremmented on every bid.\n\nThe auction will clear when the buy volume equals the sell volume at the current price.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getBuyVolume","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"type":"number"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/auctions/cleared":{"get":{"tags":["Cleared auctions"],"summary":"Cleared auctions between dates","description":"Returns the details of the cleared auctions for a given period of time.\n\n\n**The period of time is mandatory**, so you must provide either:\n* `fromDate` and `toDate` in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format.\n* or, the `period`, with one of the following values: `today`,\n  `yesterday`, `week`, `last-week`, `current-week`\n\nThe use of `fromDate` and `toDate` is **limited to a 15 days time period**. Otherwise an error will be returned\n\n\n**It returns**:\n* `auctionIndex`: Auction index of the cleared auction\n* `sellToken` and `buyToken` (plus their Ethereum addresses)\n* `auctionStart` and `auctionEnd`: Start time and clear time (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format)\n* `sellVolume` and `buyVolume`\n* `closingPrice` (note that `closingPrice = buyVolume/sellVolume`) and\n  `priceIncrement` (in percentage)\n\n\nIt can optionally be filtered by token pair (`tokenPair`).\n\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getClearedAcutionsInfo","produces":["application/json"],"parameters":[{"name":"fromDate","in":"query","description":"A date string using [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format. Required when using\n*toDate*.\n\nex: *'2018-07-01', 'YYYY-MM-DD'*","type":"string"},{"name":"toDate","in":"query","description":"A date string using [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format. Required when using\n*fromDate*.\n\nex: *'2018-07-02', 'YYYY-MM-DD'*","type":"string"},{"name":"period","in":"query","description":"A relative time period. Valid values are: *today, yesterday, week,\nlast-week, current-week*","schema":{"type":"string","enum":["today","yesterday","week","last-week","current-week"],"example":"today"}},{"name":"tokenPair","in":"query","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"required":["data","pagination"],"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/definitions/AuctionSummary"}},"pagination":{"$ref":"#/definitions/PaginationObject"}}}},"412":{"description":"<span class=\"markdown\">\n  DATE_RANGE_INVALID:\n  <ul>\n    <li>Missing params 'fromDate' and 'toDate' or 'period'.</li>\n    <li>Unknown value for period. Valid values are: today, yesterday, week, last-week, current-week</li>\n  </ul>\n  DATE_FORMAT:\n  <ul><li>Invalid date format. The required format is a valid [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format</li></ul>\n  MAX_NUM_DAYS_EXCEEDED:\n  <ul><li>Only a range of 15 days is allowed between 'toDate' and 'fromDate'</li></ul>\n</span>"}}}},"/accounts/{accountAddress}/tokens/{tokenAddress}":{"get":{"tags":["Account balances"],"summary":"Balance for a token","description":"Returns an Ethereum account's balance for a token.\n\nEvery seller and buyer, in order to submit an order, **it must deposit the tokens into the DutchX first**.\n\nEvery time a user **deposits** or **claim tokens** (from a past auction), the tokens are added to it's balance.\n\nEvery time a user **withdraw** or **submit a sell/bid order**, the tokens are deducted from the balance.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getTokenBalanceOf","produces":["application/json"],"parameters":[{"name":"accountAddress","in":"path","description":"Account address","required":true,"type":"string"},{"name":"tokenAddress","in":"path","description":"The address of the token we want to check balance","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"type":"object"}},"404":{"description":"Unknown token address"}}}},"/accounts/{accountAddress}/balances/{tokenPair}/claimable-tokens":{"get":{"tags":["Account balances"],"summary":"Claimable tokens","description":"Returns an Ethereum account's claimable tokens as buyer or seller.\n\n**As a seller**, once the auction has cleared, you should claim your tokens back. This endpoint will show you a list of any unclaimed tokens.\n\n**As a buyer**, you can claim anytime, you don't need to wait until the auction is over (you may do that, to claim only once, and to save gas though). This endpoint will show you a list of any unclaimed tokens.\n\nAlso, note that **you can claim multiple auctions at the same time**, so if you are very active in the DutchX, you may consider not claiming your tokens on every auction, and wait until you have several auctions to claim.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getClaimableTokens","produces":["application/json"],"parameters":[{"name":"accountAddress","in":"path","description":"Account address","required":true,"type":"string"},{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"type":"object","required":["sellerClaims","buyerClaims"],"properties":{"sellerClaims":{"type":"array","items":{"$ref":"#/definitions/ClaimObject"}},"buyerClaims":{"type":"array","items":{"$ref":"#/definitions/ClaimObject"}}}}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/accounts/{accountAddress}/current-liquidity-contribution-ratio":{"get":{"tags":["Account balances"],"summary":"Liquidity Contribution Ratio","description":"Returns current Liquidity Contribution ratio (percentage) for user account.\n\n**Every ask and bid in the DutchX is subjected to a LC**, that means, that a small percentage of the amount would be deducted from the order and it will be added as liquidity for next auction.\n\nThis LC ratio is, the percentage of the ask/bid order that would be deducted. The ratios are **always between `0.5%` and `0.1%`**\n\nIn order to reduce the LC you need **Magnolia tokens (MGN)**. Also, you can pay half of the fee using **OWL tokens**. For more information, checkout [https://blog.gnosis.pm/the-fee-model-7419285bf03f](https://blog.gnosis.pm/the-fee-model-7419285bf03f)\n\ni.e. If a seller post a sell order of `0.1 Ether`, and their LC ratio is `0.3%`, then `0.0003 Eth` would be deducted, so:\n* `0,0997 Ether` would be place as a sell order.\n* `0,0003 Ether` would be availible as LC for next auction.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getFeeRatio","produces":["application/json"],"parameters":[{"name":"accountAddress","in":"path","description":"An account address","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"type":"number"}}}}},"/accounts/{accountAddress}/balances/{tokenPair}/seller":{"get":{"tags":["Account auction participation"],"summary":"Current seller balance","description":"Returns account seller balance for the running auction.\nIt will return:\n* **The sell volume for the given Ethereum account**: Only if the auction is currently running. It can be `0` if the given account hasn't submitted any sell order.\n* **null**: In any other case\n\nIt's important to note, that once an auction starts, **the seller balance won't change during the auction**.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getSellerBalanceForCurrentAuction","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"},{"name":"accountAddress","in":"path","description":"An account address","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"type":"number"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/accounts/{accountAddress}/balances/{tokenPair}/auctions/{auctionIndex}/seller":{"get":{"tags":["Account auction participation"],"summary":"Seller balance for auction","description":"Returns an Ethereum's account seller balance for a given auction.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getSellerBalanceForAuction","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"},{"name":"accountAddress","in":"path","description":"An account address","required":true,"type":"string"},{"name":"auctionIndex","in":"path","description":"Auction index","required":true,"type":"integer","format":"int64"}],"responses":{"200":{"description":"successful operation","schema":{"type":"number"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/accounts/{accountAddress}/balances/{tokenPair}/buyer":{"get":{"tags":["Account auction participation"],"summary":"Current buyer balance","description":"Returns account buyer balance for the running auction.\nIt will return:\n* **The buy volume for the given Ethereum account**: Only if the auction is currently running. It can be `0` if the given account hasn't submitted any buy order.\n* **null**: In any other case\n\nIt's important to note, that when the auction starts, all accounts have `0` balance. The balance will be incremented on every buy order for the account.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getBuyerBalanceForCurrentAuction","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"},{"name":"accountAddress","in":"path","description":"An account address","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"type":"number"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}},"/accounts/{accountAddress}/balances/{tokenPair}/auctions/{auctionIndex}/buyer":{"get":{"tags":["Account auction participation"],"summary":"Buyer balance for auction","description":"Returns an Ethereum's account buyer balance for a given auction.\n\nFor more information on DutchX protocol: [https://dutchx.readthedocs.io/en/latest/mechanism.html](https://dutchx.readthedocs.io/en/latest/mechanism.html)","operationId":"getBuyerBalance","produces":["application/json"],"parameters":[{"name":"tokenPair","in":"path","description":"A token pair addresses string for selecting the desired market\n{tokenAAddress}-{tokenBAddress}.\n\nFor convenience WETH is recognized also by symbol. ex:\nWETH-{tokenBAddress}, {tokenAAddress}-WETH","required":true,"type":"string"},{"name":"accountAddress","in":"path","description":"An account address","required":true,"type":"string"},{"name":"auctionIndex","in":"path","description":"Auction index","required":true,"type":"integer","format":"int64"}],"responses":{"200":{"description":"successful operation","schema":{"type":"number"}},"404":{"description":"There is an unknown token in the token pair"},"412":{"description":"Invalid token format. Token pair format is not compilant with {tokenAAddress}-{tokenBAddress}"}}}}},"definitions":{"TokenDetails":{"type":"object","properties":{"symbol":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"decimals":{"type":"number"}},"required":["address"]},"TokenPair":{"type":"object","required":["tokenA","tokenB"],"properties":{"tokenA":{"$ref":"#/definitions/TokenDetails"},"tokenB":{"$ref":"#/definitions/TokenDetails"}}},"MarketPrice":{"type":"number","format":"double"},"PaginationObject":{"type":"object","properties":{"endingBefore":{"type":"string"},"startingAfter":{"type":"string"},"limit":{"type":"number"},"order":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string"},"direction":{"type":"string"}}}},"previousUri":{"type":"string"},"nextUri":{"type":"string"}}},"ClaimObject":{"type":"object","required":["auctionIndex","amount"],"properties":{"auctionIndex":{"type":"integer","format":"int32"},"amount":{"type":"number","format":"double"}}},"MarketState":{"type":"object","required":["isValidTokenPair","state","isSellTokenApproved","isBuyTokenApproved","auctionIndex","auctionStart","auction","auctionOpp"],"properties":{"isValidTokenPair":{"type":"boolean"},"state":{"type":"string"},"isSellTokenApproved":{"type":"boolean"},"isBuyTokenApproved":{"type":"boolean"},"auctionIndex":{"type":"integer","format":"int32"},"auctionStart":{"type":"string","format":"date-time"},"auction":{"$ref":"#/definitions/AuctionState"},"auctionOpp":{"$ref":"#/definitions/AuctionState"}}},"AuctionState":{"type":"object","required":["sellVolume","buyVolume","isClosed","isTheoreticalClosed","closingPrice","price","fundingInUSD","buyVolumesInSellTokens","priceRelationshipPercentage","boughtPercentage","outstandingVolume"],"properties":{"sellVolume":{"type":"number"},"buyVolume":{"type":"number"},"isClosed":{"type":"boolean"},"isTheoreticalClosed":{"type":"boolean"},"closingPrice":{"type":"object","properties":{"numerator":{"type":"number","format":"double"},"denominator":{"type":"number","format":"double"}}},"price":{"type":"object","properties":{"numerator":{"type":"number","format":"double"},"denominator":{"type":"number","format":"double"}}},"fundingInUSD":{"type":"number","format":"double"},"buyVolumesInSellTokens":{"type":"number","format":"double"},"priceRelationshipPercentage":{"type":"number","format":"double"},"boughtPercentage":{"type":"number","format":"double"},"outstandingVolume":{"type":"number","format":"double"}}},"AuctionSummary":{"type":"object","required":["auctionIndex","sellToken","buyToken","sellTokenAddress","buyTokenAddress","auctionStart","auctionEnd","sellVolume","buyVolume","closingPrice","priceIncrement"],"properties":{"auctionIndex":{"type":"integer","format":"int32"},"sellToken":{"type":"string"},"buyToken":{"type":"string"},"sellTokenAddress":{"type":"string"},"buyTokenAddress":{"type":"string"},"auctionStart":{"type":"string","format":"date-time"},"auctionEnd":{"type":"string","format":"date-time"},"sellVolume":{"type":"number"},"buyVolume":{"type":"number"},"closingPrice":{"type":"number","format":"double"},"priceIncrement":{"type":"number"}}}}}