Trading API Specification v1


To start the process to use Dexdex API, please complete this form.

There are two ways to obtain the exchange orders of a specific token.

  • HTTP API
  • Websocket API

Expressing volumes

Whenever in the API document you read volume (a tokens amount) & volumeEth (an ethers amount)
take in consideration that:

  • volumeEth is expressed in wei. So 1 ether = 1000000000000000000
  • volume is expressed as an integer where the N less significant digits correspond to the
    decimals of the amount. N being the ERC20 token decimal places. (e.g. If token
    decimals are 6, then an amount of 10.5 tokens is expressed as 10500000)

Order Format

An Order is an object with the following attributes:

Field Type Description
remainingVolume string Remaining volume of tokens to trade (see unit)
remainingVolumeEth string Remaining volume of ethers to trade (see unit)
price number Sell or Buy price. Expressed in eth/token
id string Unique identifier of the exchange order
token string Ethereum address of ERC20 token
isSell boolean true when the order is a sell, false when is a buy
decimals number Number of decimals of ERC20 token
ordersData string Order data bytes (used to trade w/ dexdex)

For example:

{  
  "remainingVolume":"1043561a8829300000",
  "remainingVolumeEth":"3703c0b98214000",
  "price":"2ef222c06f000",
  "id":"e6eca77dfe458539f436466473bb68ff095de3c5ec22f7ff0679efc7a288eb80",
  "token":"0x05c7065d644096a4e4c3fe24af86e36de021074b",
  "isSell":true,
  "decimals":18,
  "ordersData":"0x1acbbd9a53ead2cb8e84ee...000000000000000000000000001"
}
                

HTTP API


Path

Get list of tokens

Returns the list of tokens that are available to trade with Dexdex platform

GET /tokens/

Response: A JSON array of token objects with this format:

Field Type Description
address string Ethereum address of ERC20 token
symbol string Symbol of ERC20 token
name string Name of ERC20 token
website string Website of ERC20 token
decimals number Number of decimals of ERC20 token

Example: https://api.dexdex.io/api/v1/tokens

[
  {
    "address": [Ethereum address of the ERC20 token],
    "symbol":"TKA",
    "name":"TokenA",
    "website":"tokenA.com",
    "decimals":18
  },
  ...
]

Get buy and sell orders of a token

Returns the current list of exchange orders to trade the token.

GET /orderbooks/[TOKEN ADDRESS]

Where:

  • TOKEN ADDRESS: Ethereum address of ERC20 token.

Response: A JSON object that contains that matches:

{
  sells: Order[];  // sorted in ascending price (best price first)
  buys: Order[];   // sorted in descending price (best price first)
}

Example: https://api.dexdex.io/api/v1/orderbooks/0x05c7065d644096a4e4c3fe24af86e36de021074b

{
  "sells": [
    {  
      "remainingVolume":"1043561a8829300000",
      "remainingVolumeEth":"3703c0b98214000",
      "price":"2ef222c06f000",
      "id":"e6eca77dfe458539f436466473bb68ff095de3c5ec22f7ff0679efc7a288eb80",
      "token":"0x05c7065d644096a4e4c3fe24af86e36de021074b",
      "isSell":true,
      "decimals":18,
      "ordersData":"0x1acbbd9a53ead2cb8e84ee...000000000000000000000000001"
    },
    ...
  ],
  "buys": [
    {
      "remainingVolume":"4f68ca6d8cd91c6000000",
      "remainingVolumeEth":"2bacc83c14f000",
      "price":"7a1fbba0",
      "id":"7626b04c82497ce6ed5ca6789f850d6b24e654757abdc27ad14d52a5863e1a29",
      "token":"0x05c7065d644096a4e4c3fe24af86e36de021074b",
      "isSell":false,
      "decimals":18,
      "ordersData":"0x1aa7fd45e8cc6ceb3285b...3fe24af86e36de021074b01"
    },
    ...
  ]
}

Get the trade plan

Returns the trade plan for a given: (Token, Operation, Amount).

The trade plan consist on the best possible orders you can fill in order to do the required trade.

GET /tradeplans/[TOKEN ADDRESS]/[OPERATION]?volume=[AMOUNT]

Where:

  • TOKEN ADDRESS: Ethereum Address for the ERC20 token
  • OPERATION: string either buys or sells. The operation you want to do
  • AMOUNT: string representing the token’s volume for the operation. (see unit)

Response: A JSON object that contains the trade plan with this format:

Field Type Description
volume string trade plan’s tokens volume (see unit)
volumeEth string trade plan’s ethers volume (see unit)
orderQty number Number of orders required to execute trade plan
orderIds string[] Selected orders ids
ordersData string Bytes of data of the orders to trade

Example: https://api.dexdex.io/api/v1/tradeplans/0x05c7065d644096a4e4c3fe24af86e36de021074b/buys?volume=10500000

{   
  "volume":"10500000",
  "volumeEth":"1008015000000000",
  "orderQty":2,
  "orderIds":[
    "7626b04c82497ce6ed5ca6789f850d6b24e654757abdc27ad14d52a5863e1a29",
    "e6eca77dfe458539f436466473bb68ff095de3c5ec22f7ff0679efc7a288eb80"
  ],
  "ordersData":"0x1aa7fd45e8cc6c...6a4e4c3fe24af86e36de021074b01",
}

Get trade

Returns the information of a Dexdex trade.

GET /trades/[TRANSACTION HASH]

Where:

  • TRANSACTION HASH: Ethereum transaction hash that performed the trade.

Response: A JSON object that contains the trade information with this format:

Field Type Description
id string Unique identifier for the trade
txhash string Ethereum transaction hash where the trade was executed
state string Either: Pending, Completed, Failed. Current state of the trade
isSell boolean true if trade was a sell. false if is a buy
tradeableAddress string Ethereum address of ERC20 token
senderAddress string Ethereum address of the user who executed the trade
depositAddress string Ethereum address where the trade result was deposited
affiliateAddress string Ethereum address of the affiliate
ordersData string Bytes of data of the orders executed
gasPrice string Price of gas paid on the trade transaction (in wei)
gasUsed null or string Only if Completed or Failed. Amount of gas used on the trade transaction
volume string Amount of tokens originally requested (see unit)
volumeEth string Expected amount of ethers if full volume is filled (see unit)
volumeEffective null or string Only if Completed. Amount of tokens effectively traded (see unit)
volumeEthEffective null or string Only if Completed. Amount of ethers effectively traded (see unit)
executionDate null or string Only if Completed or Failed. ISO 8601 Date, marks when the trade was executed
updatedDate string ISO 8601 Date, marks when the trade was updated
createdDate string ISO 8601 Date, marks when the trade was created

Eg.
https://api.dexdex.io/api/v1/trades/0xa6baac337547d76267a90bdbb8d935929dd9c290ba071240237b165bbb71ebbb

{
  "id":"26c69ce0-5225-4d3b-ac9c-4f99cf104d1a",
  "txhash":"0xa6baac337547d76267a90bdbb8d935929dd9c290ba071240237b165bbb71ebbb",
  "state":"Completed",
  "isSell":false,
  "tokenAddress":"0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
  "senderAddress":"0xb94bbbcaca4eecbe427eca615789e5e19babacf7",
  "depositAddress":"0xb94bbbcaca4eecbe427eca615789e5e19babacf7",
  "affiliateAddress":"0x0000000000000000000000000000000000000000",
  "ordersData":"0x1a621c5f7b6b77...00000000000000001",
  "gasPrice":"11000000000",
  "volume":"400728000000000000",
  "volumeEth":"1005002309280962",
  "volumeEffective":"400728000000000000",
  "volumeEthEffective":"1005002309280960",
  "gasUsed":"248218",
  "executionDate":"2018-07-10T18:00:11.000Z",
  "updatedDate":"2018-07-10T18:00:21.424Z",
  "createdDate":"2018-07-10T17:59:51.568Z"
}


WebSocket API


Webscoket API using socket.io.

Allows to subscribe to and orderbook to listen to changes on it.

Path

  • wss://api.dexdex.io/socket/ (Mainnet)
  • wss://beta-api.dexdex.io/socket/ (Kovan)

Subscribe

Subscribe to a token’s orderbook.

[ "subscribe",
  {
    "tradeable":"0x8f3470a7388c05ee4e7af3d01d8c722b0ff52374",
    "withSnapshot":true
  }
]

Where:

  • tradeable: Ethereum addess for ERC20 token
  • withSnapshot: true|false. Send true to request a initial message with a snapshot of the current orderbook.

After the subscription the server will emit ob:update events, which can be:

  • Order Add Event
  • Order Update Event
  • Order Delete Event

In javascript:

socket.emit('subscribe', { tradeable: tokenAddress, withSnapshot: true }, (snapshotJson: any) => {
  // snapshotJson is the full orderbook if withSnapshot: true
  ...
});


socket.listen('ob:update', (eventJson) => {
  ...
})

The snapshotJson is an object with:

{
  sells: Order[];
  buys: Order[];
}

Where eventJson can be:

{ 
  kind: 'Add' | 'Delete' | 'Update', 
  tradeableAddress: string; // address of the token
  order: Order 
}

For example:

{
  "kind":"Delete",
  "tradeableAddress":"0x8f3470a7388c05ee4e7af3d01d8c722b0ff52374",
  "order": {  
    "remainingVolume":"57c478885e90b1ae",
    "remainingVolumeEth":"97a98498b5d09c7",
    "price":"17fb16dbf58c9fe",
    "id":"a606c5b8a9c08f99bcdee785d3921b1143d74d26e06fce92260d3121db1e4eac",
    "token":"0x8f3470a7388c05ee4e7af3d01d8c722b0ff52374",
    "isSell":false,
    "decimals":18,
    "ordersData":"0x2cd88b528fa7dfd57f...01d8c722b0ff5237401"
  }
}

Unsubscribe

Unsubscribe to a token’s orderbook

[
  "unsubscribe",
  {
    "tradeable":"0x8e10f6bb9c973d61321c25a2b8d865825f4aa57b"
  }
]

In javascript:

socket.emit('unsubscribe', { tradeable: tokenAddress }, () => {
  ...
});