swagger: '2.0' info: description: |- Welcome to DutchX API docs (read-only). On this interface you may query various information about tokens, markets, auction states, accounts of the **DutchX** protocol. All endpoints are returned to you by reading the states directly off the Ethereum blockchain from the [following smart contracts](https://dutchx.readthedocs.io/en/latest/smart-contracts_addresses.html). We provide you with the `TRY` button, such that the different endpoints can be tested from the documentation web itself. For 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: # =========================================================================== # Markets and supported tokens # =========================================================================== /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) All tokens are, at least, listed in an auction with WETH. Check “Availible markets” for a list of those that are tradable. For 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. A whitelisted token has the potential to create Magnolia tokens (used for reduction of liquidity contribution) if traded in a whitelisted pair. Tokens 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. Check “Availible markets” for a list of those that are tradable. For 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) Note that each available token pairing always runs the two opposite auctions simultaneously. For 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. Returns `true` only if the token pair has been added For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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} # =========================================================================== # Auction State # =========================================================================== '/markets/{tokenPair}/state': get: tags: - Auction state summary: General market state description: |- Returns the current state of the requested market. The result will be the general market state for the market, so it will be refering to both of the concurrent auctions: A-B and B-A It can be one of the following values: - `RUNNING` - Both auctions are currently ongoing. - `WAITING_FOR_FUNDING` - Sell volume has not reached the threshold to start - `WAITING_FOR_AUCTION_TO_START` - Sell volume threshold was reached and auction should start in next 10 minutes - `ONE_AUCTION_HAS_CLOSED` - One of the auctions it's running, the other is already closed - `PENDING_CLOSE_THEORETICAL` - All the sell volume has been bought, so the auction is closed, and the price is determined. However **it's not officially closed until the clearing process is done**. Since DutchX protocol is running in the blockchain, someone has to trigger the clearing by executing a sell order, buy order or claim action to do the clearing. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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. Aditionally, it includes information about both sides of the current auction, so for a token `A-B`, it will include the details for auction `A-B` (`auction` property) and `B-A` (`auctionOpp` property). The `state` can be one of the following values: - `RUNNING` - Both auctions are currently ongoing. - `WAITING_FOR_FUNDING` - Sell volume has not reached the threshold to start - `WAITING_FOR_AUCTION_TO_START` - Sell volume threshold was reached and auction should start in next 10 minutes - `ONE_AUCTION_HAS_CLOSED` - One of the auctions it's running, the other is already closed - `PENDING_CLOSE_THEORETICAL` - All the sell volume has been bought, so the auction is closed, and the price is determined. However **it's not officially closed until the clearing process is done**. Since DutchX protocol is running in the blockchain, someone has to trigger the clearing by executing a sell order, buy order or claim action to do the clearing. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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. Upon listing and trading, the token pair started at auction index `1`. All subsequent auctions are numbered. There is always only at most one auction running at the same time per token pair. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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. The date is in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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} # =========================================================================== # Prices # =========================================================================== '/markets/{tokenPair}/prices/running': get: tags: - Prices summary: Running auction price description: >- Current auction's bid price. This price **starts high** (double the closing price of the previous auction), and then **decreases over time**. It'll take exactly **6 hours** to decrease the price until the prior closing price. This is why auctions usually last arround 6 hours. If an auction is shorter than 6 hours, it means that it closed with a higher price (price increment). If an auction closes after more than 6 hours, means that it closed with a smaller price (price decrement), The price function **will reach `0` after `24h`** if no bidder buys the auction. The price function is the following one: `P(t) = CP * (24 - t) / ( 12 + t)` Where: * `t`: Time in hours * `CP`: Last closing price This 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. It'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). Something 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. Usually, 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`. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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. You may select how many past auctions you would like to view (`count`). You can find the auction index as well as the price increments (in %-change to the last closing price). The price A-B is read `1 A gave [value] B`. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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`. The price A-B is read `1 A gave [value] B`. To see which index the auction is currently at, check the endpoint "Auction State > Current auction index" For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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. All prices are given in Ether. The median has proven to be more resistant to market manipulation. Check here for more information about the [median](https://en.wikipedia.org/wiki/Median). You can optionally specify the auction index of the auction (`auctionIndex`), and then the number of auctions to consider in the median (`numberOfAuctions`). If you don't specify the auction index, the current auction index will be used instead. If there's not enough auctions to calculate the median it returns `null`. **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).** For 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**. The "safe" part, just means that, it **only returns a price if the following restrictions are accomplished**: * **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. * **The token is whitelisted** If no safe median price is available, it returns `null`. This endpoint just reads from the following Oracle: https://github.com/gnosis/dx-price-oracle For 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: * **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. * **requireWhitelisted**: if you require to check if the token have been whitelisted in the DutchX. By default is `true`. * **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 If it's not possible to get a price meeting the requirements, it will return `null`. **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).** This endpoint just reads from the following Oracle: https://github.com/gnosis/dx-price-oracle For 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. ex: *'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: |- INVALID_MAXIMUM_TIME_PERIOD: INVALID_NUMBER_OF_AUCTIONS: DATE_FORMAT: # =========================================================================== # Auction volumes # =========================================================================== '/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 **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. The LC **will be given to the bidders** on top of the tokens they are entitled by the closing price, so it's good for: * **Bidders**: They get more tokens, on top of the ones they bought. * **Sellers**: Since the bidders have this incentive, the auction will clear earlier, raising the price a bit, and giving sellers a better price. Note, that you have to include the auction index (`auctionIndex`). For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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. It will return: * **The sell volume**: Only if the auction is currently running. * **null**: In any other case It's important to note, that once an auction starts, **the sell volume won't change during the auction**. The auction will clear when the buy volume equals the sell volume at the current price. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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. Althougt **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. Once 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**. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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. It will return: * **The buy volume**: Only if the auction hasn'r cleared yet. * **null**: In any other case It's important to note, that the buy volume starts `0`, and then it's incremmented on every bid. The auction will clear when the buy volume equals the sell volume at the current price. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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} # =========================================================================== # Cleared auctions # =========================================================================== '/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. **The period of time is mandatory**, so you must provide either: * `fromDate` and `toDate` in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format. * or, the `period`, with one of the following values: `today`, `yesterday`, `week`, `last-week`, `current-week` The use of `fromDate` and `toDate` is **limited to a 15 days time period**. Otherwise an error will be returned **It returns**: * `auctionIndex`: Auction index of the cleared auction * `sellToken` and `buyToken` (plus their Ethereum addresses) * `auctionStart` and `auctionEnd`: Start time and clear time (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format) * `sellVolume` and `buyVolume` * `closingPrice` (note that `closingPrice = buyVolume/sellVolume`) and `priceIncrement` (in percentage) It can optionally be filtered by token pair (`tokenPair`). For 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 *toDate*. ex: *'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 *fromDate*. ex: *'2018-07-02', 'YYYY-MM-DD'* type: string - name: period in: query description: |- A relative time period. Valid values are: *today, yesterday, week, last-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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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: |- DATE_RANGE_INVALID: DATE_FORMAT: MAX_NUM_DAYS_EXCEEDED: # =========================================================================== # Account balances # =========================================================================== '/accounts/{accountAddress}/tokens/{tokenAddress}': get: tags: - Account balances summary: Balance for a token description: >- Returns an Ethereum account's balance for a token. Every seller and buyer, in order to submit an order, **it must deposit the tokens into the DutchX first**. Every time a user **deposits** or **claim tokens** (from a past auction), the tokens are added to it's balance. Every time a user **withdraw** or **submit a sell/bid order**, the tokens are deducted from the balance. For 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. **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. **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. Also, 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. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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. **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. This LC ratio is, the percentage of the ask/bid order that would be deducted. The ratios are **always between `0.5%` and `0.1%`** In 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) i.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: * `0,0997 Ether` would be place as a sell order. * `0,0003 Ether` would be availible as LC for next auction. For 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 # =========================================================================== # Account auction participation # =========================================================================== '/accounts/{accountAddress}/balances/{tokenPair}/seller': get: tags: - Account auction participation summary: Current seller balance description: >- Returns account seller balance for the running auction. It will return: * **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. * **null**: In any other case It's important to note, that once an auction starts, **the seller balance won't change during the auction**. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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. It will return: * **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. * **null**: In any other case It'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. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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. For 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 {tokenAAddress}-{tokenBAddress}. For convenience WETH is recognized also by symbol. ex: WETH-{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 externalDocs: description: Find out more about the DutchX in our blog url: 'https://blog.gnosis.pm/tagged/dutchx'