API Trading

API Trading

Lorem ipsum

Intro

dYdX Chain

Off-Chain Order Book

APIs

Numbers and Units

Running a Full Node

(better to link to running a full node page)

Full Node JSON RPC API

Block Height

The current block height can either be queried or streamed using json RPC.

Query Block Height

To query the current block height, this api can be used1 (opens in a new tab). This fetches the information about the current node which includes the block height. An example curl request is shown below:

curl --header "Content-Type: application/json" --request POST --data '{"method": "status", "id": 1}' <node-ip>:<node-port>

Stream Block Height

To stream the block height, the following api can be used2 (opens in a new tab). This api subscribes to an event and stream data via websockets. The list of events that can be subscribed to are shown in the link3 (opens in a new tab). An example curl request which subscribes to the block height event is shown below, websocat is used to stream the data.

echo '{ "jsonrpc": "2.0","method": "subscribe","id": 0,"params": {"query": "tm.event='"'NewBlock'"'"} }' | websocat -n -t ws://<json-rpc-ip>:<json-rpc-port>/websocket

Short-Term Orders

These are orders which have a finite lifetime and are valid for a short period of time. They are used to take advantage of short-term market movements. The duration of short term order can be specified either in blocks or in seconds. The duration of the order is calculated from the time the order is placed. The order is automatically cancelled after the specified duration.

All the below orders are transactions and are signed. The client4 (opens in a new tab) can be used or the transaction can be placed manually by following conforming to the formats specified here5 (opens in a new tab). For manual transactions, the transaction can be signed using the following documentation6 (opens in a new tab).

Place

To place an order, refer to the proto here7 (opens in a new tab) to understand the parameters required.

For an example of placing an order with a the client, refer to the documentation here8 (opens in a new tab).

Replace/Amend

Traders can replace Short-Term orders atomically by placing an order with the same order ID and a larger value for the good-til-block field (opens in a new tab) of the order.

Note that two orders have the same order ID if the following client-specified fields are equal (from OrderId proto definition (opens in a new tab)):

  • Subaccount ID (opens in a new tab).
    • order.subaccount_id.owner should be set to your address that is signing the order transaction.
    • order.subaccount_id.number should be set to 0 unless you are using a different subaccount.
  • Client ID.
  • Order flags (note this should always be set to 0 for placing Short-Term orders).
  • CLOB pair ID.

Assuming the current block height is 9, the below example places an order with good-til-block 10, then places a replacement order with a good-til-block of 11.

The proto for the replace order is the same as the place order9 (opens in a new tab)

For an example of replacing an order with the client, refer to the documentation here10 (opens in a new tab).

Cancel

To cancel an order, refer to the proto here11 (opens in a new tab) to understand the parameters required.

For an example of cancelling an order with the client, refer to the documentation here12 (opens in a new tab).

All Endpoints

Full Node gRPC and HTTP APIs

Stream Order Book State (L3)

Queries

Subaccount

GET /dydxprotocol/subaccounts/subaccount/{owner}/{number}

Queries subaccount state by owner and id.

Links: request / response format (opens in a new tab), RPC method definition (opens in a new tab), subaccount proto (opens in a new tab).

Balances

GET /cosmos/bank/v1beta1/balances/{address} Queries the balance of all coins for a single account.

Links: request / response format (opens in a new tab)

CLOB Pairs

GET /dydxprotocol/clob/clob_pair Queries a list of ClobPair items

Links: request / response format (opens in a new tab), RPC method definition (opens in a new tab), ClobPair proto (opens in a new tab).

Perpetuals

GET /dydxprotocol/perpetuals/perpetual Queries a list of Perpetual items.

Links: request / response format (opens in a new tab), RPC method definition (opens in a new tab), Perpetual proto (opens in a new tab).

Positions

Prices

GET /dydxprotocol/prices/market Queries a list of MarketPrice items.

Links: request / response format (opens in a new tab), RPC method definition (opens in a new tab), MarketPrice proto (opens in a new tab).

Pagination

TODO:

  • How do I paginate the queries via REST?
  • Via gRPC?
  • How can I ensure that the second page of data is from the same block height as the first? (Is this possible? didnt see a way to do this)

All Endpoints

Indexer API

Short-term vs StatefulCLI Commands