NAV Navbar
shell
  • Introduction
  • Authentication
  • Rate Limit
  • REST API
  • WebSockets API
  • Errors
  • Introduction

    The Ocean provides a simple REST API, WebSockets API, and JavaScript library to help you integrate decentralized trading into your existing trading strategy.

    This reference provides information on available endpoints and how to interact with them. To get started quickly, check out the JavaScript library on npm.

    Authentication

    # With shell, you can pass the correct header with each request
    curl "api_endpoint_here"
      -H "TOX-ACCESS-KEY: <api-key>"
      -H "TOX-ACCESS-SIGN: <signature>"
      -H "TOX-ACCESS-TIMESTAMP: <timestamp>"
    

    Credentials

    Authenticated REST and WebSockets requests require a key/secret pair, which you can create through The Ocean dashboard.

    Timestamps

    Timestamps are Unix time in microseconds.

    Signature

    To generate the correct signature, first concatenate the strings to for the prehash

    prehash = apiKey + timestamp + method + body

    Then generate the appropriate HMAC as your signature

    hmac = crypto.createHmac('sha256', secret)

    signature = hmac.update(prehash).digest('base64')

    Then include your API key, signature and timestamp in the headers to your requests.

    Rate Limit

    All IP addresses will be limited to 9000 API requests in a 5 minute period. After exceeding this limit, clients will receive a 403 error response and further requests will be blocked for 5 minutes from the time the last blocked request was made.

    REST API

    Token pairs

    curl "https://api.theocean.trade/v1/token_pairs"
    

    Example response (200)

    [
      {
        "baseToken": {
          "address": "0xa8e9fa8f91e5ae138c74648c9c304f1c75003a8d",
          "symbol": "ZRX",
          "decimals": "18",
          "minAmount": "1000000000000000000",
          "maxAmount": "100000000000000000000000",
          "precision": "-8"
        },
        "quoteToken": {
          "address": "0xc00fd9820cd2898cc4c054b7bf142de637ad129a",
          "symbol": "WETH",
          "decimals": "18",
          "minAmount": "5000000000000000",
          "maxAmount": "100000000000000000000",
          "precision": "-8"
        }
      }
    ]
    

    Retrieves all tradeable token pairs.

    HTTP Request

    GET https://api.theocean.trade/v1/token_pairs

    Response

    An array of token pair objects, each with a baseToken and a quoteToken containing the following information:

    Fields Description
    address Token address
    symbol Token symbol
    decimals The amount of token decimal places
    minAmount Minimum amount needed to submit an order
    maxAmount Maxiumum amount allowed to submit an order
    precision Level of precision for token amounts

    Ticker

    curl "https://api.theocean.trade/v1/ticker"
    

    Example response (200)

    {
      "bid": "0.00050915",
      "ask": "0.00054134",
      "last": "0.00052718",
      "volume": "3000000000000000000",
      "timestamp": "1512929327792"
    }
    
    

    Get 24 hour trading activity for a token pair.

    HTTP Request

    GET https://api.theocean.trade/v1/ticker

    URL Parameters

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address

    Response

    A price data object for a given token pair.

    Fields Description
    bid Current highest bid price
    ask Current lowest ask price
    last Last trade price
    volume 24 hour trading volume denominated in base tokens
    timestamp The end of the 24-hour period over which volume was measured (in Unix microseconds)

    Tickers

    curl "https://api.theocean.trade/v1/tickers"
    

    Example response (200)

    [{
      "baseTokenAddress": "0xa8e9fa8f91e5ae138c74648c9c304f1c75003a8d",
      "quoteTokenAddress": "0xc00fd9820cd2898cc4c054b7bf142de637ad129a",
      "ticker": {
        "bid": "0.00050915",
        "ask": "0.00054134",
        "last": "0.00052718",
        "volume": "3000000000000000000",
        "timestamp": "1512929327792"
      }
    }]
    

    Get 24 hour trading activity for all token pairs.

    HTTP Request

    GET https://api.theocean.trade/v1/tickers

    Response

    An array of price data objects for all token pairs.

    Fields Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    ticker Ticker response

    Candlesticks

    curl "https://api.theocean.trade/v1/candlesticks"
    

    Example response (200)

    [
      {
        "high": "100.52",
        "low": "97.23",
        "open": "98.45",
        "close": "99.23",
        "baseVolume": "2400000000000000000000",
        "quoteVolume": "1200000000000000000000",
        "startTime": "1512929323784"
      },
      {
        "high": "100.52",
        "low": "97.23",
        "open": "98.45",
        "close": "99.23",
        "volume": "2400000000000000000000",
        "startTime": "1512929198980"
      }
    ]
    

    Get price data for a given token pair.

    HTTP Request

    GET https://api.theocean.trade/v1/candlesticks

    Parameters

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    interval Candlestick interval (must be one of the values from candlestic intervals)
    startTime Snapshot start time (in Unix microseconds)
    endTime (optional) Snapshot end time (in Unix microseconds) (deafult is now)

    Returns

    An array of objects containing data for each interval.

    Field Description
    high Highest price
    low Lowest price
    open Price at the beginning of the interval
    close Price at the end of the interval
    baseVolume Volume of base tokens
    quoteVolume Volume of quote tokens
    startTime Start time of interval (in Unix microseconds)

    Candlesticks intervals

    curl "https://api.theocean.trade/v1/candlesticks/intervals"
    

    Example response (200)

    [
      "300",
      "900",
      "3600",
      "21600",
      "86400"
    ]
    

    Get all available candlesticks intervals.

    HTTP Request

    GET https://api.theocean.trade/v1/candlesticks/intervals

    Returns

    An array of available candlesticks intervals.

    Trade history

    curl "https://api.theocean.trade/v1/trade_history"
    

    Example response (200)

    [
      {
        "id": "37212",
        "transactionHash": "0x5e6e75e1aa681b51b034296f62ac19be7460411a2ad94042dd8ba637e13eac0c",
        "amount": "300000000000000000",
        "price": "0.00052718",
        "side": "sell", // sell | buy
        "status": "filled", // filled | settled | failed
        "lastUpdated": "1520265048996"
      }
    ]
    

    Retrieves trades for a given token pair.

    HTTP Request

    GET https://api.theocean.trade/v1/trade_history

    URL Parameters

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address

    Response

    An array of trades history events for a given token pair.

    Fields Description
    id Unique trade id
    transactionHash Hash of the ethereum transaction sent to the network
    amount Amount of base tokens exchanged
    price Price of tokens exchanged
    side Side of the trade
    status Status of the trade (one of 'CREATED', 'FILLED', 'SETTLED', 'CONFIRMED', 'ERROR', 'DEAD')
    lastUpdated Timestamp of last action (in Unix microseconds)

    Order book

    curl "https://api.theocean.trade/v1/order_book"
    

    Example response (200)

    {
      "bids": [
        {
          "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
          "price": "0.00050915",
          "availableAmount": "100000000000000000000",
          "creationTime": "1543849182000000",
          "expirationTime": "1543859182000000"
        }
      ],
      "asks": [
        {
          "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
          "price": "0.00054134",
          "availableAmount": "100000000000000000000",
          "creationTime": "1543849182000000",
          "expirationTime": "1543859182000000"
        }
      ]
    }
    

    Get the current order book for a token pair.

    HTTP Request

    GET https://api.theocean.trade/v1/order_book

    URL Parameters

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    depth (optional) The max number of orders to receive on each side of the book (default unlimitted)

    Response

    An object with arrays of bid and ask orders.

    Fields Description
    orderHash Hash of the SignedOrder sent submitted to be filled at a later time
    price Price of the order
    availableAmount Amount of tokens available to be filled
    creationTime When the order was placed (in Unix microseconds)
    expirationTime When the order will expire (in Unix microseconds)

    Order info

    curl "https://api.theocean.trade/v1/order/[orderHash]"
    

    Example response (200)

    
    {
      "baseTokenAddress": "0x7cc7fdd065cfa9c7f4f6a3c1bfc6dfcb1a3177aa",
      "quoteTokenAddress": "0x17f15936ef3a2da5593033f84487cbe9e268f02f",
      "side": "buy",
      "amount": "10000000000000000000",
      "price": "1.000",
      "created": "1512929327792",
      "expires": "1512929897118"
    }
    

    Get additional information for any open or filled order.

    HTTP Request

    GET https://api.theocean.trade/v1/order/[orderHash]

    Response

    An order object.

    Fields Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    side "buy" or "sell"
    amount Base token amount in wei
    price Price denominated in quote tokens
    created When the order was submitted
    expires When the order will expire
    feeOption Fee option selected for order
    feeTokenAddress Address that receives fee
    cancelAfter Time after which the order will be cancelled

    Available token balance

    curl "https://api.theocean.trade/v1/available_balance"
    

    Example response (200)

    {
      "availableBalance": "1001006594219628829207"
    }
    

    Returns the token balance available for new orders on The Ocean. To learn more about available balances, please visit our support page.

    HTTP Request

    (authenticated) GET https://api.theocean.trade/v1/available_balance

    Parameters

    Parameter Description
    walletAddress Ethereum wallet address
    tokenAddress Token contract address

    Returns

    The available token balance.

    Fields Description
    availableBalance Available token balance in base units

    Token balance

    curl "https://api.theocean.trade/v1/balance"
    

    Example response (200)

    {
        "available": "2410042486319284509",
        "committed": "10000000000000000000",
        "total": "12410042486319284509"
    }
    

    Returns the token available, committed and total balance for new orders on The Ocean. To learn more about available balances, please visit our support page.

    HTTP Request

    (authenticated) GET https://api.theocean.trade/v1/balance

    Parameters

    Parameter Description
    walletAddress Ethereum wallet address
    tokenAddress Token contract address

    Returns

    The available token balance.

    Fields Description
    available Available token balance in base units
    committed Committed token balance in base units
    total Total token balance in base units

    Get unsigned order

    curl "https://api.theocean.trade/v1/order/unsigned"
    
    
    

    Example response (200)

    {
      baseTokenAddress: "0x6f27fb08327c5d113c0fe3904fcdb900c6f31afe",
      quoteTokenAddress: "0x63904fcdb900c6f31afef27fb08327c5d113c0fe",
      side: "buy",
      price: "1.9923",
      amount: "10000000000000000000",
      feeAmountInTokenReceived: {
        asMaker: "-99900000000000000000",
        asTaker: "99900000000000000000"
      }
      expirationTime: "1543849182000000"
      lifecycle: "timeInForce",
      unsignedZeroExOrder: {....},
      exchangeSignature: "37800593840622773016017857006417214310534675667008850948421364357744823963318"
    }
    

    Get an unsigned limit order. This endpoint should be used along with POST /order.

    To place an order, first call this endoint with the order details. The response will contain an unsigned 0x order along with sanitized order information and a a signature from the ocean certifying that these details constitute a valid order. The user (or client library) is responsible for creating an EthSign signature and putting it in the signature field of the 0x order. The user should then POST the signed 0x order along with the sanitized order information and the exchangeSignature to the /order route.

    HTTP Request

    (authenticated) GET https://api.theocean.trade/v1/order/unsigned

    URL Parameters

    Parameter Description
    walletAddress The Ethereum address associated with the signing private key (your wallet address)
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    side "buy" or "sell"
    price Price denominated in quote tokens
    amount Base token amount in wei
    expirationTime (optional) Time at which the order will be canceled (in Unix microseconds)(default is never)
    lifecycle (optional) immedaiteOrCancel. (default is timeInForce)

    Response

    Fields Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    side buy or sell
    price The price of the order denominated in whole tokens (not base units)
    amount The amount of the order denominated in base token base units
    feeAmountInTokenReceived.asMaker The fee amount paid for the full order if it is not filled immediately. This could be negative in the case of a maker rebate
    feeAmountInTokenReceived.asTaker The fee amount paid for the full order if it is filled immediately
    expirationTime (if applicable) When the order will expire (in Unix microseconds)
    lifecycle (if applicable) One of immediateOrCancel, fillOrKill or timeInForce
    unsignedZeroExOrder A 0x order containing all fields expect for signature. To be signed by the walletAddress provided in the request
    exchangeSignature Provided by The Ocean to validate order when posted (see Submit signed order)

    Get unsigned market order

    curl "https://api.theocean.trade/v1/order/unsigned/market"
    
    
    

    Example response (200)

    {
      baseTokenAddress: "0x6f27fb08327c5d113c0fe3904fcdb900c6f31afe",
      quoteTokenAddress: "0x63904fcdb900c6f31afef27fb08327c5d113c0fe",
      side: "buy",
      amount: "10000000000000000000",
      feeAmountInTokenReceived: {
        asMaker: "-99900000000000000000",
        asTaker: "99900000000000000000"
      }
      expirationTime: "1543849182000000"
      unsignedZeroExOrder: {....},
      lifecycle: "immediateOrCancel",
      exchangeSignature: "37800593840622773016017857006417214310534675667008850948421364357744823963318"
    }
    

    Get an unsigned market order. This endpoint should be used along with POST /order.

    To place an order, first call this endoint with the order details. The response will contain an unsigned 0x order along with sanitized order information and a a signature from the ocean certifying that these details constitute a valid order. The user (or client library) is responsible for creating an EthSign signature and putting it in the signature field of the 0x order. The user should then POST the signed 0x order along with the sanitized order information and the exchangeSignature to the /order route. This endpoint serves the same purpose as GET order/unsigned. The difference being that there is no price or lifecycle provided in the body of this request. Instead, the response will have lifecycle: "immediateOrCancel" and a price will be provided in the response based on the order amount and the state of the order book. The subsequent POST call to /order/ will only be filled against available liquidity. Any unfillable portion of the order will be canceled.

    HTTP Request

    (authenticated) GET https://api.theocean.trade/v1/order/unsigned

    URL Parameters

    Parameter Description
    walletAddress The Ethereum address associated with the signing private key (your wallet address)
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    side "buy" or "sell"
    price Price denominated in quote tokens
    amount Base token amount in wei
    expirationTime (optional) Time at which the order will be canceled (in Unix microseconds)(default is never)

    Response

    Fields Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    side buy or sell
    price The price of the order denominated in whole tokens (not base units)
    amount The amount of the order denominated in base token base units
    feeAmountInTokenReceived.asMaker The fee amount paid for the full order if it is not filled immediately. This could be negative in the case of a maker rebate
    feeAmountInTokenReceived.asTaker The fee amount paid for the full order if it is filled immediately
    expirationTime (if applicable) When the order will expire (in Unix microseconds)
    lifecycle immediateOrCancel
    unsignedZeroExOrder A 0x order containing all fields expect for signature. To be signed by the walletAddress provided in the request
    exchangeSignature Provided by The Ocean to validate order when posted (see Submit signed order)

    Submit signed order

    curl "https://api.theocean.trade/v1/order"
      -X POST
    
    
    

    Order is not filled (202)

    {
      "filledAmount": "0"
      "openAmount": "1000000000000"
    }
    

    Order is filled (202)

    {
      "filledAmount": "800000000000"
      "openAmount": "200000000000",
      "transactionHash": "0x5e6e75e1aa681b51b034296f62ac19be7460411a2ad94042dd8ba637e13eac0c"
    }
    

    Submit signed orders. Use this endpoint after GET /order/unsigned to return the signed order along with the order details and the exchange signature.

    All new orders go through order validation, and the API will return an array of messages for conditions that aren't met.

    HTTP Request

    (authenticated) POST https://api.theocean.trade/v1/order

    POST Body

    Fields Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    side "buy" or "sell"
    price The price of the order denominated in whole tokens (not base units)
    amount The amount of the order denominated in base token base units
    feeAmountInTokenReceived.asMaker The fee amount paid for the full order if it is not filled immediately. This could be negative in the case of a maker rebate
    feeAmountInTokenReceived.asTaker The fee amount paid for the full order if it is filled immediately
    expirationTime (if applicable) When the order will expire (in Unix microseconds)
    lifecycle (if applicable) One of immediateOrCancel, fillOrKill or timeInForce
    signedZeroExOrder A 0x order containing all fields including an EthSign signature in the signature field
    exchangeSignature Provided by The Ocean to validate order

    Response

    An object containing the amounts filled and left open

    Fields Description
    filledAmount Amount that is immediately filled
    openAmount Amount that remains unfilled
    transactionHash Hash of the transaction in which the order was filled

    Cancel order

    curl "https://api.theocean.trade/v1/order/[orderHash]"
      -X DELETE
    
    
    

    Example response (200)

    {
      "canceledOrder": {
        "orderHash": "0x3d6b287c1dc79262d2391ae2ca9d050fdbbab2c8b3180e4a46f9f321a7f1d7a9",
        "amount": "100000000000"
      }
    }
    

    Remove an order from the order book

    HTTP Request

    (authenticated) DELETE https://api.theocean.trade/v1/order/[orderHash]

    DELETE Body

    An object confirming the details of the cancelled order.

    Fields Description
    canceledOrder.orderHash Hash of order canceled
    canceledOrder.amount Amount canceled

    Cancel all orders

    curl "https://api.theocean.trade/v1/orders"
      -X DELETE
    
    
    

    Example response (200)

    [{
      "canceledOrder": {
        "orderHash": "0x3d6b287c1dc79262d2391ae2ca9d050fdbbab2c8b3180e4a46f9f321a7f1d7a9",
        "amount": "100000000000"
      }
    }]
    

    Remove all open orders from the order book

    HTTP Request

    (authenticated) DELETE https://api.theocean.trade/v1/orders

    DELETE Body

    An array with details for each canceled order.

    Fields Description
    canceledOrder.orderHash Hash of order canceled
    canceledOrder.amount Amount canceled

    Order history

    curl "https://api.theocean.trade/v1/order_history"
    

    Example response (200)

    [
      {
        "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
        "baseTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
        "quoteTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
        "side": "buy",
        "openAmount": "10000000000000000000",
        "filledAmount": "0",
        "failedAmount": "0",
        "prunedAmount": "0",
        "settledAmount": "0",
        "confirmedAmount": "0",
        "deadAmount": "0",
        "price": "0.00050915",
        "creationTimestamp": "1512929327792000",
        "timeline": [
          {
            "action": "placed",
            "amount": "10000000000000000000",
            "timestamp": "1512929327792000"
          }
        ]
      }
    ]
    

    Retrieves all past and present orders for a user.

    HTTP Request

    (authenticated) GET https://api.theocean.trade/v1/order_history

    URL Parameters

    Parameter Description
    openAmount (optional) Return orders with an openAmount greater than or equal to this value
    settledAmount (optional) Return orders with a settledAmount greater than or equal to this value
    filledAmount (optional) Return orders with a filledAmount greater than or equal to this value
    confirmedAmount (optional) Return orders with a confirmedAmount greater than or equal to this value
    deadAmount (optional) Return orders with a deadAmount greater than or equal to this value
    prunedAmount (optional) Return orders with a prunedAmount greater than or equal to this value
    orderHash (optional) Return orders with specifed order hash
    baseTokenAddress (optional) Return orders with a baseTokenAddress equal to this value
    quoteTokenAddress (optional) Return orders with a quoteTokenAddress equal to this value
    start (optional) Return orders starting at this index
    limit (optional) Amount of orders to return (100 max)

    Response

    An array of order history event objects for all past and present user orders.

    Fields Description
    orderHash Hash of the order
    baseTokenAddress Address of base token
    quoteTokenAddress Address of quote token
    side Side of the book the order was placed
    openAmount Amount available to be filled
    reservedAmount Amount reserved by another user who has yet to sign and submit their corresponding 0x order
    filledAmount Amount filled and waiting to be submitted to the blockchain
    settledAmount Amount exchanged succesfully in a block mined with 1 confirmation on the ethereum blockchain
    confirmedAmount Amount exchanged succesfully in a block mined with 13 confirmation on the ethereum blockchain
    deadAmount Amount that will never be exchanged
    failedAmount Amount that could not be settled after one block
    prunedAmount Amount that has been pruned
    price Price denominated in quote tokens
    timeline Array of events for the order

    Order Timeline

    Events in the timeline array have the following structure:

    Fields Description
    action One of placed, filled, settled, confirmed, canceled, pruned, error, dead, returned
    amount The amount from the order that was subject to this action
    timestamp The time of the action (in Unix microseconds)
    txHash (optional) Hash of an ethereum transaction
    blockNumber (optional) Ethereum block number
    Action Description
    placed Order was placed on to the order book with an open amount
    reserved Order was put on reserve, awaiting a successful signature from the taker
    filled Order was successfully taken, tx submitted to the ethereum network
    settled Order was successfully mined in block on the ethereum blockchain, has 1 confirmation
    confirmed Order was successfully mined in block on the ethereum blockchain, has 13 confirmations
    returned Order was placed back on to the order book after being removed
    canceled Order was canceled by the user
    error Order resulted in error that comes from 0x; when transition from filled -> settled failed, or from settled -> confirmed failed
    pruned Order was removed from the book because it became unfillable

    Order Lifecycle

    Below are the most common sequences for order timelines:

    Summary Sequence
    Target order placed and taken placed -> filled -> settled -> confirmed
    Target order placed and canceled placed -> canceled
    Target order placed and pruned placed -> pruned
    Matching order submitted filled -> settled -> confirmed

    Fee components

    curl "https://api.theocean.trade/v1/fee_components"
    

    Example response (200)

    {
      "validUntil": "1532705879",
      "gasAmounts": [{
        "tokenAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "amount": "300000000000000"
      }, {
        "tokenAddress": "0xe41d2489571d322189246dafa5ebde1f4699f498",
        "amount": "129080884263348947"
      }, {
        "tokenAddress": "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2",
        "amount": "220145695137861"
      }, {
        "tokenAddress": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
        "amount": "139386787561002859"
      }],
      "feeRates": [{
        "baseTokenAddress": "0xe41d2489571d322189246dafa5ebde1f4699f498",
        "quoteTokenAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "rate": "0"
      }, {
        "baseTokenAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "quoteTokenAddress": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
        "rate": "0"
      }, {
        "baseTokenAddress": "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2",
        "quoteTokenAddress": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
        "rate": "0"
      }],
      "discountRates": {
        "ocx1": {
          "requiredBalance": "100000000000000000000",
          "rate": 0.9
        },
        "ocx2": {
          "requiredBalance": "250000000000000000000",
          "rate": 0.8
        },
        "ocx3": {
          "requiredBalance": "500000000000000000000",
          "rate": 0.7
        },
        "ocx4": {
          "requiredBalance": "1000000000000000000000",
          "rate": 0.6
        },
        "ocx5": {
          "requiredBalance": "10000000000000000000000",
          "rate": 0.5
        },
        "feeInZrx": "1",
        "whitelist": "0",
        "maker": "0.5"
      },
      "tokenMarketRates": {
        "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": {
          "price_weth": "1",
          "symbol": "WETH",
          "price_btc": "0.05826931",
          "price_usd": "463.6964",
          "from": "1532702724",
          "to": "1532705504"
        },
        "0xe41d2489571d322189246dafa5ebde1f4699f498": {
          "price_weth": "0.002324124146747742704",
          "symbol": "ZRX",
          "price_btc": "0.000135258",
          "price_usd": "1.077688",
          "from": "1532702796",
          "to": "1532705387"
        },
        "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2": {
          "price_weth": "1.362733892262264705958",
          "symbol": "MKR",
          "price_btc": "0.0794214",
          "price_usd": "631.8948",
          "from": "1532702712",
          "to": "1532705435"
        },
        "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359": {
          "price_weth": "0.002152284339494548588",
          "symbol": "DAI",
          "price_btc": "0.000125307",
          "price_usd": "0.9980065",
          "from": "1532702802",
          "to": "1532705393"
        }
      }
    }
    

    Retrieves data related to fees.

    HTTP Request

    GET https://api.theocean.trade/v1/fee_components

    Response

    Field Description
    validUntil The time until which the fee components are valid
    gasAmounts Gas fee amount in base units for each tradable token. This amount is added to every target and matching order
    feeRates Percentage of the notional amount traded that will be taken as a fee for each token pair
    discountRates Percentage of the total fee amount that will be charged for each discount
    tokenMarketRates Price conversion data for each tradable token

    Fee collection

    The total fee amount (transaction fee + gas fee) is only collected when a corresponding 0x order has successfully been mined in a block on the ethereum blockchain. The percentage of fee collected will be proportional to the percentage of the order that has successfully been settled.

    WebSockets API

    Connecting

    The Ocean requires clients to connect to the WebSockets API using socket-io. There are socket-io clients available for a variety of languages:

    Connection url: wss://ws.theocean.trade.

    JavaScript socket.io configurtion

       let sockeIOConfig = { transports: ['websocket'] }
       const io = io(this.url, sockeIOConfig)
    
    

    The Ocean handles only websocket protocol (pooling option is disabled).

    To configure socket.io to use only websockets set transports param to ['websocket']'.

    Order book

    Request

    {
      "channel": "order_book",
      "payload": {
          "baseTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
          "quoteTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
          "snapshot": "true",
          "depth": "100"
      }
    }
    

    Example snapshot response

    {
      "type": "snapshot",
      "channel": "order_book",
      "channelId": "order_book_0xef7fff64389b814a946f3e92105513705ca6b990_0xd0a1e359811322d97991e03f863a0c30c2cf029c",
      "payload":
        {
          "bids": [
            {
              "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
              "price": "0.00050915",
              "availableAmount": "100000000000000000000",
              "creationTimestamp": "1512929327792",
              "expirationTimestampInSec": "1522600583",
              "cancelAfter": null
            }
          ],
          "asks": [
            {
              "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
              "price": "0.00054134",
              "availableAmount": "100000000000000000000",
              "creationTimestamp": "1512929323784",
              "expirationTimestampInSec": "1522600583",
              "cancelAfter": null
            }
          ]
        }
    }
    

    Example update response

    {
      "type": "update",
      "channel": "order_book",
      "channelId": "order_book_0xef7fff64389b814a946f3e92105513705ca6b990_0xd0a1e359811322d97991e03f863a0c30c2cf029c",
      "payload":
        {
          "bids": [
            {
              "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
              "price": "0.00050915",
              "availableAmount": "100000000000000000000",
              "creationTimestamp": "1512929327792",
              "expirationTimestampInSec": "525600",
              "cancelAfter": null
            }
          ],
          "asks": []
        }
    }
    

    Subscribe to order book updates.

    Subscription Body

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    snapshot (optional) Send a snapshot when first subscribing
    depth (optional) Order book snapshot depth

    Response Payload

    An object with arrays of bid and ask orders.

    Field Description
    orderHash Hash of the signed order sent to The Ocean to be filled at a later time
    price Price of the order
    availableAmount Amount of tokens available to be filled
    creationTimestamp When the order was placed (in Unix microseconds)
    expirationTimestampInSec When the order will expire (in seconds)
    cancelAfter Time after which the order will be cancelled

    Candlesticks

    Request

    {
      "channel": "candlesticks",
      "payload": {
          "baseTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
          "quoteTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
          "interval": "36000000"
          "snapshot": "true",
          "startTime": "1512929327792"
      }
    }
    

    Example snapshot response

    {
      "type": "snapshot",
      "channel":"candlesticks",
      "channelId": "candlesticks_0xef7fff64389b814a946f3e92105513705ca6b990_0xd0a1e359811322d97991e03f863a0c30c2cf029c_300",
      "payload":[
        {
          "high": "100.52",
          "low": "97.23",
          "open": "98.45",
          "close": "99.23",
          "baseVolume": "2400000000000000000000",
          "quoteVolume": "1200000000000000000000",
          "startTime": "1512929323784"
        },
        {
          "high": "100.52",
          "low": "97.23",
          "open": "98.45",
          "close": "99.23",
          "volume": "2400000000000000000000",
          "startTime": "1512929198980"
        }
      ]
    }
    

    Example update response

    {
      "type": "update",
      "channel":"candlesticks",
      "channelId": "candlesticks_0xef7fff64389b814a946f3e92105513705ca6b990_0xd0a1e359811322d97991e03f863a0c30c2cf029c_300",
      "payload":[
        {
          "high": "100.52",
          "low": "97.23",
          "open": "98.45",
          "close": "99.23",
          "baseVolume": "2400000000000000000000",
          "quoteVolume": "1200000000000000000000",
          "startTime": "1512929323784"
        }
      ]
    }
    

    Subscribe to candlestick updates.

    Subscription Body

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    interval Candlestick interval
    snapshot (optional) "true" or "false". Send a snapshot when first subscribing (default "true")
    startTime (optional) Snapshot start time (in Unix microseconds) (default now)

    Response Payload

    An array of price data objects for a given token pair.

    Field Description
    high Highest price
    low Lowest price
    open Price at the beginning of the interval
    close Price at the end of the interval
    baseVolume Volume of base tokens
    quoteVolume Volume of quote tokens
    startTime Start time

    Trade history

    Request

    {
      "channel": "trade_history",
      "payload": {
          "baseTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
          "quoteTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
          "snapshot": "true"
      }
    }
    

    Example snapshot response

    {
      "type": "snapshot",
      "channel":"trade_history",
      "channelId": "trade_history_0xef7fff64389b814a946f3e92105513705ca6b990_0xd0a1e359811322d97991e03f863a0c30c2cf029c",
      "payload":[{
          "id": "37212",
          "transactionHash": "0x5e6e75e1aa681b51b034296f62ac19be7460411a2ad94042dd8ba637e13eac0c",
          "amount": "300000000000000000",
          "price": "0.00052718",
          "side": "sell",
          "status": "settled",
          "lastUpdated": "1520265078881"
        }
      ]
    }
    

    Example update response

    {
      "type": "update",
      "channel":"trade_history",
      "channelId": "trade_history_0xef7fff64389b814a946f3e92105513705ca6b990_0xd0a1e359811322d97991e03f863a0c30c2cf029c",
      "payload":[{
          "id": "37212",
          "transactionHash": "0x5e6e75e1aa681b51b034296f62ac19be7460411a2ad94042dd8ba637e13eac0c",
          "amount": "300000000000000000",
          "price": "0.00052718",
          "side": "buy",
          "status": "settled",
          "lastUpdated": "1520265078881"
        }
      ]
    }
    

    Subscribe to trade history updates.

    Subscription Body

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    snapshot (optional) Send a snapshot when first subscribing

    Response Payload

    An array of trade history events for a given token pair.

    Field Description
    id Unique trade id
    transactionHash Hash of the ethereum transaction sent to the network
    amount Amount of base tokens exchanged
    price Price of tokens exchanged
    side Side of the trade
    status State of the trade
    lastUpdated Last updated timestamp (in Unix microseconds)

    Order history

    Request

    {
      "channel": "order_history",
      "payload": {
          "snapshot": "true"
      }
    }
    

    Example snapshot response

    {
      "type": "snapshot",
      "channel": "order_history",
      "channelId": "order_history",
      "payload": [{
          "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
          "baseTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
          "quoteTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
          "side": "buy"
          "openAmount": "0",
          "filledAmount": "10000000000000000000",
          "reservedAmount": "0",
          "settledAmount": "0",
          "confirmedAmount": "0",
          "deadAmount": "0",
          "price": "0.00050915",
          "timeline": [
            {
              "action": "placed",
              "amount": "10000000000000000000",
              "timestamp": "1512929327792"
            }
          ]
        }
      ]
    }
    

    Example update response

    {
      "type": "update",
      "channel": "order_history",
      "channelId": "order_history",
      "payload": {
        "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
        "baseTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
        "quoteTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
        "side": "buy"
        "openAmount": "0",
        "reservedAmount": "0",
        "filledAmount": "10000000000000000000",
        "settledAmount": "0",
        "confirmedAmount": "0",
        "deadAmount": "0",
        "price": "0.00050915",
        "timeline": [
          {
            "action": "placed",
            "amount": "10000000000000000000",
            "timestamp": "1512929327792"
          },
          {
            "action": "filled",
            "amount": "10000000000000000000",
            "timestamp": "1512929805948"
          }
        ]
      }
    }
    

    Subscribe to order history updates.

    Subscription Body (authenticated)

    Parameter Description
    snapshot (optional) Send a snapshot when first subscribing

    Response Payload

    An array of order history events.

    Field Description
    orderHash Hash of the order
    baseTokenAddress Address of base token
    quoteTokenAddress Address of quote token
    side Side of the book the order was placed
    openAmount Amount available to be filled
    reservedAmount Amount reserved by another user who has yet to sign and submit their corresponding 0x order
    filledAmount Amount filled and waiting to be submitted to the blockchain
    settledAmount Amount exchanged succesfully in a block mined with 1 confirmation on the ethereum blockchain
    confirmedAmount Amount exchanged succesfully in a block mined with 13 confirmation on the ethereum blockchain
    deadAmount Amount that will never be exchanged
    price Price denominated in quote tokens
    timeline Array of events for the order

    Ticker Stats

    Request

    {
      "channel": "ticker_stats",
      "payload": {
          "baseTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
          "quoteTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
          "snapshot": "true"
      }
    }
    

    Example snapshot response

    {
      "type": "snapshot",
      "channel":"ticker_stats",
      "channelId": "ticker_stats_0xef7fff64389b814a946f3e92105513705ca6b990_0xd0a1e359811322d97991e03f863a0c30c2cf029c",
      "payload":[{
          "last": "0.00052718",
          "volume": "3000000000000000000",
          "timestamp": "1512929327792"
        }
      ]
    }
    

    Example update response

    {
      "type": "update",
      "channel":"ticker_stats",
      "channelId": "ticker_stats_0xef7fff64389b814a946f3e92105513705ca6b990_0xd0a1e359811322d97991e03f863a0c30c2cf029c",
      "payload":[{
          "last": "0.002234",
          "volume": "4000000000000000000",
          "timestamp": "1512929327792"
        }
      ]
    }
    

    Subscribe to ticker stats updates.

    WebSockets Request

    wss://ws.theocean.trade

    Subscription Body

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    snapshot (optional) Send a snapshot when first subscribing

    Response Payload

    Trading activity for a token pair

    Field Description
    last Last trade price
    volume Amount of base tokens traded in the last 24 hours
    timestamp The end of the 24-hour period over which volume was measured

    Errors

    The Ocean uses the following error request codes:

    Error Code Meaning
    400 Bad Request -- Your request was invalid.
    404 Not Found -- Unknown API entry point.
    405 Method Not Allowed -- You tried to access data with an invalid method.
    406 Not Acceptable -- You requested a format that isn't json.
    429 Too Many Requests -- Request rate limit was applied.
    500 Internal Server Error -- The server encountered an error.
    503 Service Unavailable -- The server is temporarily offline for maintenance.

    Order Validation

    The Ocean will return an array of messages if a new order fails order validation. Below are descriptions for each message to help you avoid submitting invalid orders:

    Error Message Description
    Fillable amount under minimum [SYMBOL] trade size. The token amount required from you to immediately fill an order must meet the minimum amount allowed on the exchange. Minimum and maximum amounts for all tokens are included in the GET /token_pairs endpoint.
    Price can't exceed [PRECISION] digits in precision. Price precision is not allowed to exceed the price precision limit set for a given quote token.
    Greater than available wallet balance. The token amount required from you for the order can't be above your available wallet balance on The Ocean. To learn more about available balances, please visit our support page.
    Token traded must be unlocked. For each token you'd like to trade, you will need to first give the 0x Exchange Contract permission to update your wallet balance for that token. You can do this through The Ocean dashboard or with the set token allowance method in the JS client library. To learn more about unlocking tokens, please visit our support page.
    Self trading is not allowed. The Ocean does not allow users to take their own order. This is enforced on user accounts and wallet addresses.
    [FIELD] has a negative value. Parameters for an order can't be negative.
    Orderbook exhausted This error occurs when creating market order if there is not enough liquidity in order book.
    OrderHash cannot be recreated When posting signed order, The Ocean tries to recreate order hash from submitted signedOrder attributes. If submitted orderHash does not match recreated orderHash, this error will be thrown.
    Invalid exchange signature The Ocean validates exchangeSignature when posting signedOrder. If signature is deemed invalid, this error will be thrown.
    Invalid signedZeroExOrder signature The Ocean validates signedZeroExOrder signature. If invalid, this error will be thrown.