NAV Navbar
shell
  • Introduction
  • Authentication
  • Rate Limit
  • REST API
  • WebSockets API
  • Client Library
  • 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 in milliseconds.

    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/v0/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/v0/token_pairs

    Response

    An array of token pair objects.

    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/v0/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/v0/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 Amount of base tokens traded in the last 24 hours
    timestamp The end of the 24-hour period over which volume was measured

    Tickers

    curl "https://api.theocean.trade/v0/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/v0/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/v0/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/v0/candlesticks

    Parameters

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    interval Candlestick interval
    startTime Snapshot start time
    endTime (optional) Snapshot end time

    Returns

    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

    Candlesticks intervals

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

    Example response (200)

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

    Get all available candlesticks intervals.

    HTTP Request

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

    Returns

    An array of available candlesticks intervals.

    Trade history

    curl "https://api.theocean.trade/v0/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 the last 100 trades for a given token pair.

    HTTP Request

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

    URL Parameters

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address

    Response

    An array of the last 100 trade 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 State of the trade
    lastUpdated Last updated timestamp

    Order book

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

    Example response (200)

    {
      "bids": [
        {
          "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
          "price": "0.00050915",
          "availableAmount": "100000000000000000000",
          "creationTimestamp": "1512929327792",
          "expirationTimestampInSec": "525600"
        }
      ],
      "asks": [
        {
          "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
          "price": "0.00054134",
          "availableAmount": "100000000000000000000",
          "creationTimestamp": "1512929323784",
          "expirationTimestampInSec": "525600"
        }
      ]
    }
    

    Get the current order book for a token pair.

    HTTP Request

    GET https://api.theocean.trade/v0/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

    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
    creationTimestamp When the order was placed
    expirationTimestampInSec The number of seconds untill the order will expire

    Order info

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

    Example response (200)

    
    {
      "baseTokenAddress": "0x7cc7fdd065cfa9c7f4f6a3c1bfc6dfcb1a3177aa",
      "quoteTokenAddress": "0x17f15936ef3a2da5593033f84487cbe9e268f02f",
      "side": "buy",
      "amount": "10000000000000000000",
      "price": "1.000",
      "created": "1512929327792",
      "expires": "1512929897118",
      "zeroExOrder": {
        "exchangeContractAddress": "0x516bdc037df84d70672b2d140835833d3623e451",
        "maker": "0x006dc83e5b21854d4afc44c9b92a91e0349dda13",
        "taker": "0x00ba938cc0df182c25108d7bf2ee3d37bce07513",
        "makerTokenAddress": "0x7cc7fdd065cfa9c7f4f6a3c1bfc6dfcb1a3177aa",
        "takerTokenAddress": "0x17f15936ef3a2da5593033f84487cbe9e268f02f",
        "feeRecipient": "0x88a64b5e882e5ad851bea5e7a3c8ba7c523fecbe",
        "makerTokenAmount": "10000000000000000000",
        "takerTokenAmount": "10000000000000000000",
        "makerFee": "0",
        "takerFee": "0",
        "expirationUnixTimestampSec": "525600",
        "salt": "37800593840622773016017857006417214310534675667008850948421364357744823963318",
        "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
        "ecSignature": {
          "v": 28,
          "r": "0x5307b6a69e7cba8583e1de39efb93a9ae1afc11849e79d99f462e49c18c4d6e4",
          "s": "0x5950e82364227ccca95c70b47375e8911a2039d3040ba0684329634ebdced160"
        }
      }
    }
    

    Get additional information for any open or filled order.

    HTTP Request

    GET https://api.theocean.trade/v0/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
    exchangeContractAddress Address of the Exchange contract. This address will change each time the protocol is updated
    maker Address originating the order
    taker (optional) Address permitted to fill the order
    makerToken Address of an ERC20 Token contract
    takerToken Address of an ERC20 Token contract
    makerTokenAmount Total units of makerToken offered by maker
    takerTokenAmount Total units of takerToken requested by maker
    expirationTimestampInSec Time at which the order expires (seconds since unix epoch)
    salt Arbitrary number that allows for uniqueness of the order's Keccak SHA3 hash
    feeRecipient (optional) Address that recieves transaction fees
    makerFee Total units of ZRX paid to feeRecipient by maker
    takerFee Total units of ZRX paid to feeRecipient by taker
    orderHash Order hash
    ecSignature ECDSA signature of the above arguments

    Available token balance

    curl "https://api.theocean.trade/v0/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/v0/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/v0/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/v0/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 limit order

    curl "https://api.theocean.trade/v0/limit_order/reserve"
    
    
    

    Order is not immediately fillable (200)

    {
      "unsignedTargetOrder": {
        "exchangeContractAddress": "0x516bdc037df84d70672b2d140835833d3623e451",
        "maker": "",
        "taker": "0x00ba938cc0df182c25108d7bf2ee3d37bce07513",
        "makerTokenAddress": "0x7cc7fdd065cfa9c7f4f6a3c1bfc6dfcb1a3177aa",
        "takerTokenAddress": "0x17f15936ef3a2da5593033f84487cbe9e268f02f",
        "feeRecipient": "0x88a64b5e882e5ad851bea5e7a3c8ba7c523fecbe",
        "makerTokenAmount": "10000000000000000000",
        "takerTokenAmount": "10000000000000000000",
        "makerFee": "0",
        "takerFee": "0",
        "expirationUnixTimestampSec": "525600",
        "salt": "37800593840622773016017857006417214310534675667008850948421364357744823963318",
        "ecSignature": {
          "v": 0,
          "r": "",
          "s": ""
        }
      }
    }
    

    Order is partially immediately fillable (200)

    {
      "unsignedTargetOrder": {
        "exchangeContractAddress": "0x516bdc037df84d70672b2d140835833d3623e451",
        "maker": "",
        "taker": "0x00ba938cc0df182c25108d7bf2ee3d37bce07513",
        "makerTokenAddress": "0x7cc7fdd065cfa9c7f4f6a3c1bfc6dfcb1a3177aa",
        "takerTokenAddress": "0x17f15936ef3a2da5593033f84487cbe9e268f02f",
        "feeRecipient": "0x88a64b5e882e5ad851bea5e7a3c8ba7c523fecbe",
        "makerTokenAmount": "10000000000000000000",
        "takerTokenAmount": "10000000000000000000",
        "makerFee": "0",
        "takerFee": "0",
        "expirationUnixTimestampSec": "525600",
        "salt": "37800593840622773016017857006417214310534675667008850948421364357744823963318",
        "ecSignature": {
          "v": 0,
          "r": "",
          "s": ""
        }
      },
      "unsignedMatchingOrder": {
        "exchangeContractAddress": "0x516bdc037df84d70672b2d140835833d3623e451",
        "maker": "",
        "taker": "0x00ba938cc0df182c25108d7bf2ee3d37bce07513",
        "makerTokenAddress": "0x7cc7fdd065cfa9c7f4f6a3c1bfc6dfcb1a3177aa",
        "takerTokenAddress": "0x17f15936ef3a2da5593033f84487cbe9e268f02f",
        "feeRecipient": "0x88a64b5e882e5ad851bea5e7a3c8ba7c523fecbe",
        "makerTokenAmount": "10000000000000000000",
        "takerTokenAmount": "10000000000000000000",
        "makerFee": "0",
        "takerFee": "0",
        "expirationUnixTimestampSec": "525600",
        "salt": "37800593840622773016017857006417214310534675667008850948421364357744823963318",
        "ecSignature": {
          "v": 0,
          "r": "",
          "s": ""
        }
      },
      "matchingOrderID": "MARKET_INTENT:8ajjh92s1r8ajjh92s1sjjh92s1t"
    }
    

    Order is completely immediately fillable (200)

    {
      "unsignedMatchingOrder": {
        "exchangeContractAddress": "0x516bdc037df84d70672b2d140835833d3623e451",
        "maker": "",
        "taker": "0x00ba938cc0df182c25108d7bf2ee3d37bce07513",
        "makerTokenAddress": "0x7cc7fdd065cfa9c7f4f6a3c1bfc6dfcb1a3177aa",
        "takerTokenAddress": "0x17f15936ef3a2da5593033f84487cbe9e268f02f",
        "feeRecipient": "0x88a64b5e882e5ad851bea5e7a3c8ba7c523fecbe",
        "makerTokenAmount": "10000000000000000000",
        "takerTokenAmount": "10000000000000000000",
        "makerFee": "0",
        "takerFee": "0",
        "expirationUnixTimestampSec": "525600",
        "salt": "37800593840622773016017857006417214310534675667008850948421364357744823963318",
        "ecSignature": {
          "v": 0,
          "r": "",
          "s": ""
        }
      },
      "matchingOrderID": "MARKET_INTENT:8ajjh92s1r8ajjh92s1sjjh92s1t"
    }
    

    Get a signable limit order and signable market order, if needed. 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/v0/limit_order/reserve

    URL Parameters

    Parameter Description
    walletAddress Your Wallet Address
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    side "buy" or "sell"
    orderAmount Base token amount in wei
    price Price denominated in quote tokens
    feeOption Fees can be paid in native currency ("feeInNative"), or ZRX ("feeInZRX")
    cancelAfter (optional) Timestamp with expiration time. Must match range now + [0, 60] s

    Response

    An object containing a limit and/or market order on reserve to be signed and submitted.

    Fields Description
    unsignedTargetOrder Signable order to place to the order book
    unsignedMatchingOrder Signable order immediately fillable
    matchingOrderID Unique market order id

    Add limit order

    curl "https://api.theocean.trade/v0/limit_order/place"
      -X POST
    
    
    

    Order is not immediately fillable (200)

    {
      "targetOrder": {
        "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
        "amount": "100000000000"
      }
    }
    

    Order is partially immediately fillable (200)

    {
      "targetOrder": {
        "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
        "amount": "100000000000"
      },
      "matchingOrder": {
        "orderHash": "0x3d6b287c1dc79262d2391ae2ca9d050fdbbab2c8b3180e4a46f9f321a7f1d7a9",
        "transactionHash": "0x5e6e75e1aa681b51b034296f62ac19be7460411a2ad94042dd8ba637e13eac0c",
        "amount": "100000000000"
      }
    }
    

    Order is completely immediately fillable (200)

    {
      "matchingOrder": {
        "orderHash": "0x3d6b287c1dc79262d2391ae2ca9d050fdbbab2c8b3180e4a46f9f321a7f1d7a9",
        "transactionHash": "0x5e6e75e1aa681b51b034296f62ac19be7460411a2ad94042dd8ba637e13eac0c",
        "amount": "100000000000"
      }
    }
    

    Submit signed limit and/or market orders. 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/v0/limit_order/place

    POST Body

    Fields Description
    signedTargetOrder Signed order to place to the order book
    signedMatchingOrder (optional) Signed order immediately fillable
    matchingOrderID (optional) Unique market order id

    Response

    An object confirming the details of limit and/or market order submitted.

    Fields Description
    targetOrder.orderHash Hash of order placed onto the order book
    targetOrder.amount Amount of target order
    matchingOrder.orderHash Hash of order sent for settlement to the blockchain
    matchingOrder.transactionHash Hash of the settlement transaction sent to the blockchain
    matchingOrder.amount Amount of matching order

    Get market order

    curl "https://api.theocean.trade/v0/market_order/reserve"
    
    
    

    Order is not immediately fillable (200)

    
    

    Order is partially immediately fillable (200)

    
    

    Order is completely immediately fillable (200)

    {
      "unsignedMatchingOrder": {
        "exchangeContractAddress": "0x516bdc037df84d70672b2d140835833d3623e451",
        "maker": "",
        "taker": "0x00ba938cc0df182c25108d7bf2ee3d37bce07513",
        "makerTokenAddress": "0x7cc7fdd065cfa9c7f4f6a3c1bfc6dfcb1a3177aa",
        "takerTokenAddress": "0x17f15936ef3a2da5593033f84487cbe9e268f02f",
        "feeRecipient": "0x88a64b5e882e5ad851bea5e7a3c8ba7c523fecbe",
        "makerTokenAmount": "10000000000000000000",
        "takerTokenAmount": "10000000000000000000",
        "makerFee": "0",
        "takerFee": "0",
        "expirationUnixTimestampSec": "525600",
        "salt": "37800593840622773016017857006417214310534675667008850948421364357744823963318",
        "ecSignature": {
          "v": 0,
          "r": "",
          "s": ""
        }
      },
      "matchingOrderID": "MARKET_INTENT:8ajjh92s1r8ajjh92s1sjjh92s1t"
    }
    

    Get a signable market order. 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/v0/market_order/reserve

    URL Parameters

    Parameter Description
    walletAddress Your Wallet Address
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    side "buy" or "sell"
    orderAmount Base token amount in wei
    feeOption Fees can be paid in native currency ("feeInNative"), or ZRX ("feeInZRX")

    Response

    An object containing a market order on reserve to be signed and submitted.

    Fields Description
    unsignedMatchingOrder Signable order immediately fillable
    matchingOrderID Unique market order id

    Add market order

    curl "https://api.theocean.trade/v0/market_order/place"
      -X POST
    
    
    

    Example response (200)

    {
      "matchingOrder": {
        "orderHash": "0x3d6b287c1dc79262d2391ae2ca9d050fdbbab2c8b3180e4a46f9f321a7f1d7a9",
        "transactionHash": "0x5e6e75e1aa681b51b034296f62ac19be7460411a2ad94042dd8ba637e13eac0c",
        "amount": "100000000000"
      }
    }
    

    Submit a signed market order. 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/v0/market_order/place

    POST Body

    Fields Description
    signedMatchingOrder Signed order immediately fillable
    matchingOrderID Unique market order id

    Response

    An object confirming the details of the market order submitted.

    Fields Description
    matchingOrder.orderHash Hash of order sent for settlement to the blockchain
    matchingOrder.transactionHash Hash of the settlement transaction sent to the blockchain
    matchingOrder.amount Amount of matching order

    Cancel order

    curl "https://api.theocean.trade/v0/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/v0/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/v0/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/v0/orders

    DELETE Body

    An array with details for each canceled order.

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

    User history

    curl "https://api.theocean.trade/v0/user_history"
    

    Example response (200)

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

    Retrieves all past and present orders for a user.

    HTTP Request

    (authenticated) GET https://api.theocean.trade/v0/user_history

    URL Parameters

    Parameter Description
    openAmount (optional) Return orders with an openAmount greater than or equal to this value (default = 0)
    reservedAmount (optional) Return orders with a reservedAmount 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
    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 user 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
    price Price denominated in quote tokens
    timeline Array of events for the order

    Order Timeline

    Each entry in user history returns the current state for each order, and the timeline will contain the current sequence events that occured to affect the current order state.

    Each timeline event will contain the following data:

    Fields Description
    action Action taken on the order
    amount Amount of the order affected by the action
    timestamp Time the action was taken on the order
    intentID (optional) Ocean intent ID
    txHash (optional) Hash of an ethereum transaction
    blockNumber (optional) Ethereum block number

    Below are the possible timeline actions that can occur for an order:

    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
    dead Order is dead; after part of an order is not longer possible to use
    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/v0/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/v0/fee_components

    Response

    Field Description
    validUntil The timestamp until which the fee components are no longer 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": "525600"
            }
          ],
          "asks": [
            {
              "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
              "price": "0.00054134",
              "availableAmount": "100000000000000000000",
              "creationTimestamp": "1512929323784",
              "expirationTimestampInSec": "525600"
            }
          ]
        }
    }
    

    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"
            }
          ],
          "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 0cean 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
    expirationTimestampInSec The number of seconds until the order will expire

    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) Send a snapshot when first subscribing
    startTime (optional) Snapshot start time

    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

    User history

    Request

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

    Example snapshot response

    {
      "type": "snapshot",
      "channel": "user_history",
      "channelId": "user_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": "user_history",
      "channelId": "user_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 user history updates.

    Subscription Body (authenticated)

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

    Response Payload

    An array of user 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

    Client Library

    Setup

    For full trading functionality, The Ocean JavaScript library requires API credentials and a web3 provider to be passed during instantiation. You can create API credentials through The Ocean dashboard.

    import createOcean from 'the-ocean'
    
    const ocean = createOcean({
      api: {
        key: 'your key',
        secret: 'your secret'
      },
      baseURL: 'https://api.theocean.trade/v0/',
      websockets: https://ws.theocean.trade,
      web3Provider: web3.currentProvider
    })
    
    

    If API credentials are omitted, trade methods will be unavailable.

    // no api credentials
    const ocean = createOcean({
      baseURL: 'https://api.theocean.trade/v0/',
      websockets: https://ws.theocean.trade,
      web3Provider: web3.currentProvider
    })
    
    console.log(typeof ocean.trade) // "undefined"
    

    Token pairs

    Example call

    const pairs = await ocean.marketData.tokenPairs();
    console.log(pairs);
    

    Example response

    [
      {
        "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"
        }
      }
    ]
    

    Get all tradeable token pairs on The Ocean.

    Returns

    An array of token pair objects.

    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

    Example call

    const ticker = await ocean.marketData.ticker({
      baseTokenAddress: pair.baseToken.address,
      quoteTokenAddress: pair.quoteToken.address
    });
    
    console.log(ticker);
    

    Example response

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

    Get 24 hour trading activity for a token pair.

    Parameters

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address

    Returns

    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 Amount of base tokens traded in the last 24 hours
    timestamp The end of the 24-hour period over which volume was measured

    Tickers

    Example call

    const tickers = await ocean.marketData.tickers();
    console.log(tickers);
    

    Example response

    [{
      "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.

    Returns

    An array of price data objects for all token pairs.

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

    Order book

    Example call

    const orderBook = await ocean.marketData.orderBook({
      baseTokenAddress: pair.baseToken.address,
      quoteTokenAddress: pair.quoteToken.address,
      depth: 100
    });
    console.log(orderBook);
    

    Example response

    {
      "bids": [
        {
          "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
          "price": "0.00050915",
          "availableAmount": "100000000000000000000",
          "creationTimestamp": "1512929327792",
          "expirationTimestampInSec": "525600"
        }
      ],
      "asks": [
        {
          "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
          "price": "0.00054134",
          "availableAmount": "100000000000000000000",
          "creationTimestamp": "1512929323784",
          "expirationTimestampInSec": "525600"
        }
      ]
    }
    

    Get the current order book for a token pair.

    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

    Returns

    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
    creationTimestamp When the order was placed
    expirationTimestampInSec The number of seconds untill the order will expire

    Trade history

    Example call

    const tradeHistory = await ocean.marketData.tradeHistory({
      baseTokenAddress: pair.baseToken.address,
      quoteTokenAddress: pair.quoteToken.address
    });
    console.log(tradeHistory);
    

    Example response

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

    Retrieves the last 100 trades for a given token pair.

    Parameters

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address

    Returns

    An array of the last 100 trade 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
    status State of the trade
    lastUpdated Last updated timestamp

    Candlesticks

    Example call

    const candlesticks = await ocean.marketData.candlesticks({
      baseTokenAddress: pair.baseToken.address,
      quoteTokenAddress: pair.quoteToken.address,
      startTime: parseInt(Date.now() / 1000 - 3600),
      endTime: parseInt(Date.now() / 1000),
      interval: 3600
    });
    console.log(candlesticks);
    

    Example response

    [
      {
        "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 historical candlestick data.

    Parameters

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    startTime Start time in UNIX epoch time
    endTime (optional) End time in UNIX epoch time
    interval Candlestick interval in seconds. Must be one of : 5 minutes, 15 minutes, 1 hour, 6 hours, 24 hours

    Returns

    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

    Candlesticks intervals

    const candlesticksInterval = await ocean.marketData.candlesticksIntervals();
    console.log(candlesticksIntervals);
    

    Example response

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

    Get all available candlesticks intervals.

    Returns

    An array of available candlesticks intervals.

    Order info

    Example call

    const orderBook = await ocean.marketData.orderBook({
      baseTokenAddress: pair.baseToken.address,
      quoteTokenAddress: pair.quoteToken.address
    });
    const topBid = orderBook.bids[0];
    
    if(topBid){
      const hash = topBid.orderHash;
      const topBidOrder = await ocean.marketData.orderInfo(hash);
      console.log(topBidOrder);
    }
    

    Example response

    {
      "baseTokenAddress": "0x7cc7fdd065cfa9c7f4f6a3c1bfc6dfcb1a3177aa",
      "quoteTokenAddress": "0x17f15936ef3a2da5593033f84487cbe9e268f02f",
      "side": "buy",
      "amount": "10000000000000000000",
      "price": "1.000",
      "created": "1512929327792",
      "expires": "1512929897118",
      "zeroExOrder": {
        "exchangeContractAddress": "0x516bdc037df84d70672b2d140835833d3623e451",
        "maker": "0x006dc83e5b21854d4afc44c9b92a91e0349dda13",
        "taker": "0x00ba938cc0df182c25108d7bf2ee3d37bce07513",
        "makerTokenAddress": "0x7cc7fdd065cfa9c7f4f6a3c1bfc6dfcb1a3177aa",
        "takerTokenAddress": "0x17f15936ef3a2da5593033f84487cbe9e268f02f",
        "feeRecipient": "0x88a64b5e882e5ad851bea5e7a3c8ba7c523fecbe",
        "makerTokenAmount": "10000000000000000000",
        "takerTokenAmount": "10000000000000000000",
        "makerFee": "0",
        "takerFee": "0",
        "expirationUnixTimestampSec": "525600",
        "salt": "37800593840622773016017857006417214310534675667008850948421364357744823963318",
        "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
        "ecSignature": {
          "v": 28,
          "r": "0x5307b6a69e7cba8583e1de39efb93a9ae1afc11849e79d99f462e49c18c4d6e4",
          "s": "0x5950e82364227ccca95c70b47375e8911a2039d3040ba0684329634ebdced160"
        }
      }
    }
    

    Get additional information for any open or filled order.

    Returns

    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
    exchangeContractAddress Address of the Exchange contract. This address will change each time the protocol is updated
    maker Address originating the order
    taker (optional) Address permitted to fill the order
    makerToken Address of an ERC20 Token contract
    takerToken Address of an ERC20 Token contract
    makerTokenAmount Total units of makerToken offered by maker
    takerTokenAmount Total units of takerToken requested by maker
    expirationTimestampInSec Time at which the order expires (seconds since unix epoch)
    salt Arbitrary number that allows for uniqueness of the order's Keccak SHA3 hash
    feeRecipient (optional) Address that recieves transaction fees
    makerFee Total units of ZRX paid to feeRecipient by maker
    takerFee Total units of ZRX paid to feeRecipient by taker
    orderHash Order hash
    ecSignature ECDSA signature of the above arguments

    Cancel order

    Example call

    const canceled = await ocean.trade.cancelOrder(orderHash);
    console.log(canceled);
    

    Example response

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

    Parameters

    Fields Description
    orderHash Hash of existing order

    Returns

    An object confirming the details of the cancelled order.

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

    Cancel all orders

    Example call

    const canceled = await ocean.trade.cancelAllOrders();
    console.log(canceled);
    

    Example response

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

    Returns

    An array with details for each canceled order.

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

    Add limit order

    Example call

    const limit = await ocean.trade.newLimitOrder({
      walletAddress: "your wallet address",
      baseTokenAddress: pair.baseToken.address,
      quoteTokenAddress: pair.quoteToken.address,
      side: "buy",
      orderAmount: "10000000000000000000",
      feeOption: 'feeInNative',
      price: "0.01"
    })
    console.log(limit)
    

    Example response

    Order is not immediately fillable (200)

    {
      "targetOrder": {
        "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
        "amount": "100000000000"
      }
    }
    

    Order is partially immediately fillable (200)

    {
      "targetOrder": {
        "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
        "amount": "100000000000"
      },
      "matchingOrder": {
        "orderHash": "0x3d6b287c1dc79262d2391ae2ca9d050fdbbab2c8b3180e4a46f9f321a7f1d7a9",
        "transactionHash": "0x5e6e75e1aa681b51b034296f62ac19be7460411a2ad94042dd8ba637e13eac0c",
        "amount": "100000000000"
      }
    }
    

    Order is completely immediately fillable (200)

    {
      "matchingOrder": {
        "orderHash": "0x3d6b287c1dc79262d2391ae2ca9d050fdbbab2c8b3180e4a46f9f321a7f1d7a9",
        "transactionHash": "0x5e6e75e1aa681b51b034296f62ac19be7460411a2ad94042dd8ba637e13eac0c",
        "amount": "100000000000"
      }
    }
    

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

    Parameters

    Parameter Description
    walletAddress Your Wallet Address
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    side "buy" or "sell"
    orderAmount Base token amount in wei
    feeOption Fees can be paid in native currency ("feeInNative"), or ZRX ("feeInZRX")
    price Price denominated in quote tokens

    Returns

    An object confirming the details of limit and/or market order submitted.

    Fields Description
    targetOrder.orderHash Hash of order placed onto the order book
    targetOrder.amount Amount of target order
    matchingOrder.orderHash Hash of order sent for settlement to the blockchain
    matchingOrder.transactionHash Hash of the settlement transaction sent to the blockchain
    matchingOrder.amount Amount of matching order

    Add market order

    Example call

    const market = await ocean.trade.newMarketOrder({
      walletAddress: "your wallet address",
      baseTokenAddress: pair.baseToken.address,
      quoteTokenAddress: pair.quoteToken.address,
      side: "buy",
      orderAmount: "10000000000000000000",
      feeOption: 'feeInNative'
    })
    console.log(market)
    

    Example response

    {
      "matchingOrder": {
        "orderHash": "0x3d6b287c1dc79262d2391ae2ca9d050fdbbab2c8b3180e4a46f9f321a7f1d7a9",
        "transactionHash": "0x5e6e75e1aa681b51b034296f62ac19be7460411a2ad94042dd8ba637e13eac0c",
        "amount": "100000000000"
      }
    }
    

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

    Parameters

    Parameter Description
    walletAddress Your Wallet Address
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    side "buy" or "sell"
    orderAmount Base token amount in wei
    feeOption Fees can be paid in native currency ("feeInNative"), or ZRX ("feeInZRX")

    Returns

    An object confirming the details of the market order submitted.

    Fields Description
    matchingOrder.orderHash Hash of order sent for settlement to the blockchain
    matchingOrder.transactionHash Hash of the settlement transaction sent to the blockchain
    matchingOrder.amount Amount of matching order

    User history

    Example call

    const myHistory = await ocean.trade.userHistory();
    console.log(myHistory);
    

    Example response

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

    Retrieves all past and present orders for a user.

    Parameter Description
    openAmount (optional) Return orders with an openAmount greater than or equal to this value (default = 0)
    reservedAmount (optional) Return orders with a reservedAmount 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
    baseTokenAddress (optional) Return orders with a baseTokenAddress equal to this value
    quoteTokenAddress (optional) Return orders with a quoteTokenAddress equal to this value

    Returns

    An array of user 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
    price Price denominated in quote tokens
    timeline Array of events for the order

    Fee components

    Example call

    const comps = await ocean.trade.feeComponents();
    console.log(comps);
    

    Example response

    {
      "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.

    Returns

    Fields Description
    validUntil The timestamp until which the fee components are no longer 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

    Get available token balance

    Example call

    const balance = await ocean.trade.getTokenAvailableBalance({
      walletAddress: web3.eth.defaultAccount,
      tokenAddress: pair.baseToken.address
    })
    console.log(balance)
    

    Example response

    {
      "availableBalance": "1001006594219628829207"
    }
    

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

    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

    Get token balance

    Example call

    const balance = await ocean.wallet.getTokenBalance({
      walletAddress: web3.eth.defaultAccount,
      tokenAddress: pair.baseToken.address
    })
    console.log(balance)
    

    Example response

    {
        "available": BigNumber,
        "committed": BigNumber,
        "total": "BigNumber
    }
    

    Parameters

    Parameter Description
    walletAddress Ethereum wallet address
    tokenAddress Token contract address

    Returns

    The new token balance.

    Fields Description
    available BigNumber.js object representing current available token balance
    total BigNumber.js object representing current token total balance
    committed BigNumber.js object representing current token committed balance

    Get token allowance

    Example call

    const allowance = await ocean.wallet.getTokenAllowance({
      walletAddress: web3.eth.defaultAccount,
      tokenAddress: pair.baseToken.address
    })
    console.log(allowance)
    

    Example response

    BigNumber
    

    Parameters

    Parameter Description
    walletAddress Ethereum wallet address
    tokenAddress Token contract address

    Returns

    The current token allowance.

    Fields Description
    BigNumber BigNumber.js object representing current token allowance

    Set token allowance

    Example call

    const result = await ocean.wallet.setTokenAllowance({
      walletAddress: web3.eth.defaultAccount,
      tokenAddress: pair.baseToken.address,
      amountInWei: '100000000000000'
    })
    console.log(result)
    

    Example response

    BigNumber
    

    Parameters

    Parameter Description
    walletAddress Ethereum wallet address
    tokenAddress Token contract address
    amountInWei Amount in base units

    Returns

    The new token allowance.

    Fields Description
    BigNumber BigNumber.js object representing new token allowance

    Set unlimited token allowance

    Example call

    const result = await ocean.wallet.setTokenAllowanceUnlimited({
      walletAddress: web3.eth.defaultAccount,
      tokenAddress: pair.baseToken.address
    })
    console.log(result)
    

    Example response

    BigNumber
    

    Parameters

    Parameter Description
    walletAddress Ethereum wallet address
    tokenAddress Token contract address

    Returns

    The new token allowance.

    Fields Description
    BigNumber BigNumber.js object representing new token allowance

    Wrap ether

    Example call

    const result = await ocean.wallet.wrapEth({
      amountInWei: '1000000000000',
      address: web3.eth.defaultAccount,
      gasPrice: '41000000000000',
      gasLimit: '1000000000000'
    })
    console.log(result)
    

    Example response

    BigNumber
    

    Parameters

    Parameter Description
    amountInWei Amount in base units
    address Ethereum wallet address
    gasPrice (optional) Gas price for the transaction
    gasLimit (optional) Gas limit for the transaction

    Returns

    The amount of ether successfully wrapped.

    Fields Description
    BigNumber BigNumber.js object representing amount wrapped

    Unwrap wrapped ether

    Example call

    const result = await ocean.wallet.unwrapEth({
      amountInWei: '1000000000000',
      address: web3.eth.defaultAccount,
      gasPrice: '41000000000000',
      gasLimit: '1000000000000'
    })
    console.log(result)
    

    Example response

    BigNumber
    

    Parameters

    Parameter Description
    amountInWei Amount in base units
    address Ethereum wallet address
    gasPrice (optional) Gas price for the transaction
    gasLimit (optional) Gas limit for the transaction

    Returns

    The amount of weth successfully unwrapped.

    Fields Description
    BigNumber BigNumber.js object representing amount unwrapped

    WebSockets - Establishing connection

    Example call

    try {
      await ocean.ws.connect()
    } catch (e) {
      // handle error
    }
    

    You will need to call ws.connect() before subscribing to a channel. e is going to contain property wsConnectionError set to true if the problem was estabilishing a connection to the Websocket server.

    WebSockets - Order book

    Example call

    await ocean.ws.connect()
    const update = function(res){
      // update
    }
    
    ocean.ws.subscribe('order_book', {
      baseTokenAddress: pair.baseTokenAddress,
      quoteTokenAddress: pair.quoteTokenAddress,
      snapshot: true
    }, update)
    

    Example response

    {
      "bids": [
        {
          "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
          "price": "0.00050915",
          "availableAmount": "100000000000000000000",
          "creationTimestamp": "1512929327792",
          "expirationTimestampInSec": "525600"
        }
      ],
      "asks": [
        {
          "orderHash": "0x94629386298dee69ae63cd3e414336ae153b3f02cffb9ffc53ad71e166615618",
          "price": "0.00054134",
          "availableAmount": "100000000000000000000",
          "creationTimestamp": "1512929323784",
          "expirationTimestampInSec": "525600"
        }
      ]
    }
    

    Parameters

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

    Returns

    An object with arrays of bid and ask orders.

    Field Description
    orderHash Hash of the signed order sent to the 0cean 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
    expirationTimestampInSec The number of seconds until the order will expire

    WebSockets - Candlesticks

    Example call

    await ocean.ws.connect()
    const update = function(res){
      // update
    }
    
    ocean.ws.subscribe('candlesticks', {
      baseTokenAddress: pair.baseTokenAddress,
      quoteTokenAddress: pair.quoteTokenAddress,
      interval: 36000000,
      snapshot: true,
      startTime: 1512929327792
    }, update)
    

    Example response

    [
      {
        "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"
      }
    ]
    

    Parameters

    Parameter Description
    baseTokenAddress Base token address
    quoteTokenAddress Quote token address
    interval Candlestick interval
    snapshot (optional) Send a snapshot when first subscribing
    startTime (optional) Snapshot start time

    Returns

    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

    WebSockets - Trade history

    Example call

    await ocean.ws.connect()
    const update = function(res){
      // update
    }
    
    ocean.ws.subscribe('trade_history', {
      baseTokenAddress: pair.baseTokenAddress,
      quoteTokenAddress: pair.quoteTokenAddress,
      snapshot: true
    }, update)
    

    Example response

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

    Parameters

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

    Returns

    An array of the last 100 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
    status State of the trade
    lastUpdated Last updated timestamp

    WebSockets - Ticker Stats

    Example call

    await ocean.ws.connect()
    const update = function(res){
      // update
    }
    
    ocean.ws.subscribe('ticker_stats', {
      baseTokenAddress: pair.baseTokenAddress,
      quoteTokenAddress: pair.quoteTokenAddress,
      snapshot: true
    }, update)
    

    Example response

     {
        "last": "0.00052718",
        "volume": "3000000000000000000",
        "timestamp": "1512929327792"
     }
    

    Parameters

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

    Returns

    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

    WebSockets - User history

    Example call

    await ocean.ws.connect()
    const update = function(res){
      // update
    }
    
    ocean.ws.subscribe('user_history', {
      snapshot: true
    }, update)
    

    Example response

    {
      "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"
        }
      ]
    }
    

    Parameters

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

    Returns

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

    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

    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 over maximum [SYMBOL] trade size. The token amount required from you to immediately fill an order can't exceed the maximum amount allowed on the exchange. Minimum and maximum amounts for all tokens are included in the GET /token_pairs endpoint.
    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.
    Error during reservation. 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.