API Reference

Endpoint

The Radar Relay API is a RESTful API that implements the 0x standard relayer specification. In order to sign and fill orders on a 0x based relayer API, the API will need to be utilized in conjunction with the 0x.js library.The Radar dev team is currently working hard to release an accompanying SDK to simplify the use of this API.


Pagination

Requests that return multiple items should respond to the ?page and ?per_page parameters. For example:

Page numbering should be 1-indexed, not 0-indexed.

These requests include the token_pairs, orders, and orderbook endpoints.


Rate Limiting

Rate limit guidance for clients can be optionally returned in the response headers:

Header Name Description
X-RateLimit-Limit The maximum number of requests you're permitted to make per hour.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

When a rate limit is exceeded, a status of 429 Too Many Requests should be returned.


Errors

Unless the spec defines otherwise, errors to bad requests should respond with HTTP 4xx or status codes.

Common error codes

Code Reason
400 Bad Request – Invalid request format
404 Not found
429 Too many requests - Rate limit exceeded
500 Internal Server Error
501 Not Implemented

Misc.

  • All requests and responses should be of application/json content type
  • All token amounts are sent in amounts of the smallest level of precision (base units). (e.g if a token has 18 decimal places, selling 1 token would show up as selling '1000000000000000000' units by this API).
  • All addresses are sent as lower-case (non-checksummed) Ethereum addresses with the 0x prefix.

REST API

GET /token_pairs

Retrieves a list of available token pairs and the information required to trade them. This endpoint should be paginated.

Parameters

  • tokenA=&tokenB [string] – returns token pairs that contain tokenA and tokenB (in any order). Setting only tokenA or tokenB returns pairs filtered by that token only

Response

  • address - address of the token
  • minAmount - the minimum trade amount the relayer will accept
  • maxAmount - the maximum trade amount the relayer will accept
  • precision - the desired price precision a relayer would like to support within their orderbook

GET /orders

Retrieves a list of orders given query parameters. This endpoint should be paginated. For querying an entire orderbook snapshot, the orderbook endpoint is recommended.

Parameters

  • exchangeContractAddress [string] - returns orders created for this exchange address
  • tokenAddress [string] - returns orders where makerTokenAddress or takerTokenAddress is token address
  • makerTokenAddress [string] - returns orders with specified makerTokenAddress
  • takerTokenAddress [string] - returns orders with specified makerTokenAddress
  • tokenA=&tokenB [string] - returns orders where makerTokenAddress and takerTokenAddress are tokenA or tokenB
  • maker [string] - returns orders where maker is maker address
  • taker [string] - returns orders where taker is taker address
  • trader [string] - returns orders where maker or taker is trader address
  • feeRecipient [string] - returns orders where feeRecipient is feeRecipient address

If both makerTokenAddress and takerTokenAddress are specified, returned orders will be sorted by price determined by (takerTokenAmount/makerTokenAmount) in ascending order. By default, orders returned by this endpoint are unsorted.


GET /order/{orderHash}

Retrieves a specific order by orderHash.

Returns HTTP 404 if no order with specified orderHash was found.


GET /orderbook

Retrieves the orderbook for a given token pair.

Parameters

  • baseTokenAddress [string] – address of token designated as the baseToken in the currency pair calculation of price (required)
  • quoteTokenAddress [string] - address of token designated as the quoteToken in the currency pair calculation of price (required)

Bids will be sorted in descending order by price, and asks will be sorted in ascending order by price. Within the price sorted orders, the orders are further sorted first by total fees, then by expiration in ascending order.


POST /fees

Given an unsigned order without the fee-related properties, returns the required feeRecipient, makerFee, and takerFee of that order.


POST /order

Submit a 0x SignedOrder to Radar. For more information on signing a 0x order see: getOrderHashHex and signOrderHashAsync


Websocket API

Websocket Subscriptions

Websocket events can be subscribed to by sending a json payload via wss://api.radarrelay.com/0x/v0/ws.


Orderbook Channel

Subscribe Parameters

  • baseTokenAddress - address of token designated as the baseToken in the currency pair calculation of price (required)
  • quoteTokenAddress - address of token designated as the quoteToken in the currency pair calculation of price (required)
  • snapshot - if true, a snapshot of the orderbook will be sent before any updates to the orderbook
  • limit - maximum number of bids and asks in orderbook snapshot

Snapshot Event

  • channelId - a numeric channel identifier for each subscribed channel. This id is static per session.
  • bids - array of signed orders where takerTokenAddress is equal to baseTokenAddress
  • asks - array of signed orders where makerTokenAddress is equal to baseTokenAddress

Bids will be sorted in descending order by price, and asks will be sorted in ascending order by price. Within the price sorted orders, the orders are further sorted first by total fees, then by expiration in ascending order.

Update Event

Once subscribed to the orderbook channel for a specific pair, you will begin to receive update events.

API Endpoint

https://api.radarrelay.com/0x/v0/

Example Pagination

curl "https://api.radarrelay.com/0x/v0/orders?page=3&per_page=20"

Rate Limit Response

curl -i https://api.radarrelay.com/0x/v0/token_pairs
  HTTP/1.1 200 OK
  Date: Mon, 20 Oct 2017 12:30:06 GMT
  Status: 200 OK
  X-RateLimit-Limit: 60
  X-RateLimit-Remaining: 56
  X-RateLimit-Reset: 1372700873

Error Response

View schema

{
    "code": 101,
    "reason": "Validation failed",
    "validationErrors": [
        {
            "field": "maker",
            "code": 1002,
            "reason": "Invalid address"
        }
    ]
}

General error codes:

  100 - Validation Failed
  101 - Malformed JSON
  102 - Order submission disabled
  103 - Throttled

Validation error codes:

  1000 - Required field
  1001 - Incorrect format
  1002 - Invalid address
  1003 - Address not supported
  1004 - Value out of range
  1005 - Invalid ECDSA or Hash
  1006 - Unsupported option

Token Pairs Response

View schema

[
  {
      "tokenA": {
          "address": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
          "minAmount": "0",
          "maxAmount": "10000000000000000000",
          "precision": 5
      },
      "tokenB": {
          "address": "0xef7fff64389b814a946f3e92105513705ca6b990",
          "minAmount": "0",
          "maxAmount": "50000000000000000000",
          "precision": 5
      }
  },
  ...
]

Orders Response

View schema

[
     {
         "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
         "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
         "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
         "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
         "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
         "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
         "makerTokenAmount": "10000000000000000",
         "takerTokenAmount": "20000000000000000",
         "makerFee": "100000000000000",
         "takerFee": "200000000000000",
         "expirationUnixTimestampSec": "42",
         "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
         "ecSignature": {
             "v": 27,
             "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
             "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
         }
     },
     ...
 ]
 

Order Response

View schema

{
   "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
   "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
   "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
   "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
   "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
   "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
   "makerTokenAmount": "10000000000000000",
   "takerTokenAmount": "20000000000000000",
   "makerFee": "100000000000000",
   "takerFee": "200000000000000",
   "expirationUnixTimestampSec": "42",
   "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
   "ecSignature": {
       "v": 27,
       "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
       "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
   }
}

Order Book Response

View schema

{
   "bids": [
       {
           "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
           "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
           "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
           "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
           "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
           "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
           "makerTokenAmount": "10000000000000000",
           "takerTokenAmount": "20000000000000000",
           "makerFee": "100000000000000",
           "takerFee": "200000000000000",
           "expirationUnixTimestampSec": "42",
           "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
           "ecSignature": {
               "v": 27,
               "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
               "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
           }
       },
       ...
   ],
   "asks": [
       {
           "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
           "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
           "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
           "makerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
           "takerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
           "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
           "makerTokenAmount": "22000000000000000",
           "takerTokenAmount": "10000000000000000",
           "makerFee": "100000000000000",
           "takerFee": "200000000000000",
           "expirationUnixTimestampSec": "632",
           "salt": "54515451557974875123697849345751275676157243756715784155226239582178",
           "ecSignature": {
               "v": 27,
               "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
               "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
           }
       },
       ...
   ]
}

Fees Request

View schema

{
  "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
  "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
  "taker": "0x0000000000000000000000000000000000000000",
  "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
  "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
  "makerTokenAmount": "10000000000000000",
  "takerTokenAmount": "20000000000000000",
  "expirationUnixTimestampSec": "42",
  "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500"
}

Fees Response

View schema

{
   "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
   "makerFee": "100000000000000",
   "takerFee": "200000000000000"
 }
 

Order Request

View schema

{
  "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
  "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
  "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
  "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
  "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
  "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
  "makerTokenAmount": "10000000000000000",
  "takerTokenAmount": "20000000000000000",
  "makerFee": "100000000000000",
  "takerFee": "200000000000000",
  "expirationUnixTimestampSec": "42",
  "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
  "ecSignature": {
      "v": 27,
      "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
      "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
  }
}

Order Response

Returns HTTP 201 on success

Example Client Connection (Node):

const WebSocketClient = require('websocket').client;
const client = new WebSocketClient();

client.on('connect', function(connection) {
    console.log('Connected to Server...');

    connection.on('message', function(message) {
      if (message.type === 'utf8') {
        console.log(message.utf8Data);
      }
    });

    function send(message) {
      if (connection.connected) {
          connection.sendUTF(message);
      }
    }

    // subscribe with snapshot
    send(`{
        "type": "subscribe",
        "channel": "orderbook",
        "payload": {
            "baseTokenAddress": "0x2956356cd2a2bf3202f771f50d3d14a367b48070",
            "quoteTokenAddress": "0xe41d2489571d322189246dafa5ebde1f4699f498",
            "snapshot": true,
            "limit": 100
        }
    }`);
});

client.connect('wss://api.radarrelay.com/0x/v0/ws');

WS Orderbook Subscribe Request

View schema

{
 "type": "subscribe",
 "channel": "orderbook",
 "payload": {
   "baseTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
   "quoteTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
   "snapshot": true,
   "limit": 100
   }
}
 

Orderbook Snapshot Event

View schema

{
   "type": "snapshot",
   "channel": "orderbook",
   "channelId": 1,
   "payload": {
       "bids": [
           {
               "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
               "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
               "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
               "makerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
               "takerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
               "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
               "makerTokenAmount": "22000000000000000",
               "takerTokenAmount": "10000000000000000",
               "makerFee": "100000000000000",
               "takerFee": "200000000000000",
               "expirationUnixTimestampSec": "632",
               "salt": "54515451557974875123697849345751275676157243756715784155226239582178",
               "ecSignature": {
                   "v": 27,
                   "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
                   "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
               }
           },
           ...
       ],
       "asks": [
           {
               "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
               "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
               "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
               "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
               "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
               "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
               "makerTokenAmount": "10000000000000000",
               "takerTokenAmount": "20000000000000000",
               "makerFee": "100000000000000",
               "takerFee": "200000000000000",
               "expirationUnixTimestampSec": "42",
               "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
               "ecSignature": {
                   "v": 27,
                   "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
                   "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
               }
           },
           ...
       ]
   }

}

Orderbook Update Event

View schema

{
       "type": "update",
       "channel": "orderbook",
       "channelId": 1,
       "payload": {
           "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
           "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
           "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
           "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
           "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
           "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
           "makerTokenAmount": "10000000000000000",
           "takerTokenAmount": "20000000000000000",
           "makerFee": "100000000000000",
           "takerFee": "200000000000000",
           "expirationUnixTimestampSec": "42",
           "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
           "ecSignature": {
               "v": 27,
               "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
               "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
           }
       }
   }