General

These docs describe the v3 API for the dYdX decentralized perpetual contracts exchange. The exchange runs on an L2 (layer-2) blockchain system, and operates independently of previous dYdX protocols and systems, including the v1 and v2 APIs.

Like the previous iteration of dYdX perpetuals, the exchange uses a centralized order book, but remains non-custodial, and settles trades and liquidations in a trustless manner.

Layer 2: ZK-Rollups

Trades are settled in an L2 (layer-2) system, which publishes ZK (zero-knowledge) proofs periodically to an Ethereum smart contract in order to prove that state transitions within L2 are valid. Funds must be deposited to the Ethereum smart contract before they can be used to trade on dYdX.

By settling trades on L2, the exchange is able to offer much higher trade throughput and lower minimum order sizes, compared with systems settling trades directly on Ethereum (i.e. L1). This is achieved while maintaining decentralization, and the exchange is fully non-custodial.

The L2 system was developed with, and is operated jointly with, Starkware. More information about the L2 design can be found in Starkware's documentation. (Note: Some of the details described there may be specific to Starkware's previous StarkEx system and may not apply to the dYdX system.)

Data Centers

Our data centers are located in the AWS US-EAST-1 region (Northern Virginia).

Number Formats

All amounts and prices in the clients and API are represented in “human readable,” natural units. For example, an amount of 1.25 ETH is represented as 1.25, and a price of $31,000.50 per BTC is represented as 31000.5.

Base URLs

Base URLs for API endpoints are as follows:

• Production (Mainnet): https://api.dydx.exchange
• Staging (Ropsten): https://api.stage.dydx.exchange

Testnet

We have one testnet which is on Ropsten. To use the testnet, use the above Staging URL for your endpoint. Also use a networkId of 3 (Ropsten) instead of 1 (Mainnet).

The user interface for testnet can be found here.

The dYdX Ropsten USDC token address is 0x8707a5bf4c2842d46b31a405ba41b858c0f876c4. We have no automated faucet at this time. Please reach out to dYdX if you need testnet tokens.

Rate-Limits

All rate-limits are subject to change.

Please make use of the WebSockets API if you need real-time data.

Rate Limit - API

Limits are enforced by IP Address for public endpoints, and by both IP Address and Account for private endpoints.

Note the following fields in the header of the server response in order to manage your remaining limits: RateLimit-Remaining, RateLimit-Reset, Retry-After, RateLimit-Limit.

Rate Limit - Websocket

Limits are enforced per connectionId for subscribe messages.

Cancel-Order Rate Limits

Canceling orders is limited per asset-pair and is intended to be higher than the limit on placing orders.

DELETE v3/orders requests are limited to 3 requests per 10 seconds per asset-pair.

DELETE v3/orders/:id requests are limited to 250 requests per 10 seconds per asset-pair.

Place-Order Rate-Limits

Order rate limits are limited to maxPoints spent (per asset-pair) in a fixed window of windowSec seconds.

We want to give priority to those who are making the largest orders and who are contributing the most liquidity to the exchange. Therefore, placing larger orders is subject to higher limits (i.e. larger orders carry a lower point cost). The point cost is based on the orderNotional which is equal to the size * price of the order.

Limit-order point consumption is equal to:

orderConsumption = clamp(
  ceil(targetNotional / orderNotional),
  minOrderConsumption,
  maxOrderConsumption
)

Each order type (Limit, Market, Triggerable) has a different minOrderConsumption. Limit orders that are Fill-or-Kill or Immediate-or-Cancel are considered to be market orders for the purposes of rate limiting.

At the time of writing, below are listed the current values, but the most up-to-date values of the above variables can be found in the v3/config endpoint.

Other Limits

Accounts may only have up to 20 open orders for a given market/side pair at any one time. (For example up to 20 open BTC-USD bids).

Perpetual Contracts

The dYdX Perpetual is a non-custodial, decentralized margin product that offers synthetic exposure to a variety of assets.

Margin

Collateral is held as USDC, and the quote asset for all perpetual markets is USDC. Cross-margining is used by default, meaning an account can open multiple positions that share the same collateral. Isolated margin can be achieved by creating separate accounts (sub-accounts) under the same user.

Each market has three risk parameters, the initialMarginFraction, maintenanceMarginFraction and incrementalInitialMarginFraction, which determine the max leverage available within that market. These are used to calculate the value that must be held by an account in order to open or increase positions (in the case of initial margin) or avoid liquidation (in the case of maintenance margin).

Risk Parameters and Related Fields

Portfolio Margining

There is no distinction between realized and unrealized PnL for the purposes of margin calculations. Gains from one position will offset losses from another position within the same account, regardless of whether the profitable position is closed.

Margin Calculation

The margin requirement for a single position is calculated as follows:

Initial Margin Requirement = abs(S × P × I)
Maintenance Margin Requirement = abs(S × P × M)

Where:

• S is the size of the position (positive if long, negative if short)
• P is the oracle price for the market
• I is the initial margin fraction for the market
• M is the maintenance margin fraction for the market

The margin requirement for the account as a whole is the sum of the margin requirement over each market i in which the account holds a position:

Total Initial Margin Requirement = Σ abs(Si × Pi × Ii)
Total Maintenance Margin Requirement = Σ abs(Si × Pi × Mi)

The total margin requirement is compared against the total value of the account, which incorporates the quote asset (USDC) balance of the account as well as the value of the positions held by the account:

Total Account Value = Q + Σ (Si × Pi)

The Total Account Value is also referred to as equity.

Where:

• Q is the account's USDC balance (note that Q may be negative)
• S and P are as defined above (note that S may be negative)

An account cannot open new positions or increase the size of existing positions if it would lead the total account value of the account to drop below the total initial margin requirement. If the total account value ever falls below the total maintenance margin requirement, the account may be liquidated.

Free collateral is calculated as:

Free collateral = Total Account Value - Total Initial Margin Requirement

Equity and free collateral can be tracked over time using the latest oracle price (obtained from the markets websocket).

Liquidations

Accounts whose total value falls below the maintenance margin requirement (described above) may have their positions automatically closed by the liquidation engine. Positions are closed at the close price described below. Profits or losses from liquidations are taken on by the insurance fund.

Close Price for Liquidations

The close price for a position being liquidated is calculated as follows, depending whether it is a short or long position:

Close Price (Short) = P × (1 + (M × V / W))
Close Price (Long) = P × (1 − (M × V / W))

Where:

• P is the oracle price for the market
• M is the maintenance margin fraction for the market
• V is the total account value, as defined above
• W is the total maintentance margin requirement, as defined above

This formula is chosen such that the ratio V / W is unchanged as individual positions are liquidated.

Funding

Funding payments are exchanged between long and short traders to encourage the price of a perpetual contract to trade close to the price of the underlying. If the perpetual trades at a premium relative to the index, long traders will typically make payments to short traders, whereas if the perpetual trades at a discount relative to the index, short traders will typically make payments to long traders.

The payments are credited or debited at the start of each hour, and are included in the realized PnL for the position.

Funding payments can be found by calling Get /v3/funding and the predicted funding rate can be found by calling Get v3/markets.

Funding Rate Units

Since funding payments are exchanged every hour, the dYdX funding rate is usually represented as a 1-hour rate, which represents the return a position may expect to earn or pay every hour.

When calculating the funding rate, the premium is scaled to have a realization period of 8 hours. That means, for example, that if a certain perpetual market trades consistently at a 0.1% premium relative to the underlying, long traders may expect to pay ~0.1% every 8 hours, and short traders may expect to earn a ~0.1% return every 8 hours (not accounting for the interest rate component).

Funding Payment Calculation

At the start of each hour, an account receives USDC (if F is positive) or pays USDC (if F is negative) in an amount equal to:

F = (-1) × S × P × R

Where:

• S is the size of the position (positive if long, negative if short)
• P is the oracle price for the market
• R is the funding rate (as a 1-hour rate)

Funding Rate Calculation

The main component of the funding rate is a premium that takes into account market activity for the perpetual. It is calculated for each market, every minute (at a random point within the minute) using the formula:

Premium = (Max(0, Impact Bid Price - Index Price) - Max(0, Index Price - Impact Ask Price)) / Index Price

Where the impact bid and impact ask prices are defined as:

Impact Bid Price = Average execution price for a market sell of the impact notional value
Impact Ask Price = Average execution price for a market buy of the impact notional value

And the impact notional amount for a market is:

Impact Notional Amount = 500 USDC / Initial Margin Fraction

For example, for a market with a 10% initial margin fraction, the impact notional value is 5,000 USDC.

At the end of each hour, the premium component is calculated as the simple average (i.e. TWAP) of the 60 premiums calculated over the course of the last hour. In addition to the premium component, each market has a fixed interest rate component that aims to account for the difference in interest rates of the base and quote currencies. The funding rate is then:

Funding Rate = (Premium Component / 8) + Interest Rate Component

Currently, the interest rate component for all dYdX markets is 0.00125% (equivalent to 0.01% per 8 hours).

Contract Loss Mechanisms

During periods of high volatility in the markets underlying the perpetual contracts, the value of some accounts may drop below zero before they can be liquidated.

The insurance fund is the first backstop to maintain the solvency of the system when an account has a negative balance. The account will be liquidated, and the insurance fund will take on the loss.

In the event that the insurance fund is depleted, positions with the most profit and leverage may be used to offset negative-balance accounts, in order to maintain the stability of the system.

Index Price Sources

ETH-USD

• Binance
• Bitstamp
• CoinbasePro
• Gemini
• Kraken

BTC-USD

• Bitstamp
• Bittrex
• CoinbasePro
• Gemini
• Kraken

LINK-USD

• Binance
• CoinbasePro
• Huobi
• kraken
• OKEx

USDT-USD

• Binance
• Bitfinex
• FTX
• Huobi
• Kraken
• OKEx

AAVE-USD

• Binance
• OKEx
• CoinbasePro
• Huobi
• Gemini
• Kraken
• Uniswap_V2

UNI-USD

• OKEx
• Binance
• Huobi
• CoinbasePro
• Kraken
• FTX
• Gemini
• Uniswap_V2

SUSHI-USD

• Binance
• OKEx
• Huobi
• Bitfinex
• FTX
• SushiSwap

SOL-USD

• Binance
• Bitfinex
• OKEx
• Huobi
• FTX

YFI-USD

• Binance
• OKEx
• Huobi
• Kraken
• Bitfinex
• FTX
• Gemini
• SushiSwap
• Uniswap_V2
• CoinbasePro

1INCH-USD

• Binance
• Huobi
• OKEx
• Gemini
• FTX

AVAX-USD

• Binance
• OKEx
• Gate
• Huobi
• Bitfinex

SNX-USD

• Binance
• OKEx
• Huobi
• Gemini
• Kraken
• FTX
• SushiSwap
• Uniswap_V2
• CoinbasePro

CRV-USD

• Binance
• OKEx
• Huobi
• Kraken
• Gemini
• SushiSwap
• Uniswap_V2
• CoinbasePro

UMA-USD

• Binance
• OKEx
• SushiSwap
• Huobi
• Gemini
• CoinbasePro

DOT-USD

• Binance
• Huobi
• OKEx
• Kraken
• Bitfinex

DOGE-USD

• Binance
• Huobi
• OKEx
• Kraken
• FTX

MATIC-USD

• Binance
• CoinbasePro
• OKEx
• Huobi
• FTX

MKR-USD

• CoinbasePro
• Binance
• Huobi
• Uniswap_V2
• OKEx
• FTX

FIL-USD

• Huobi
• Binance
• OKEx
• CoinbasePro
• Kraken
• Gemini

ADA-USD

• Binance
• CoinbasePro
• Huobi
• Kraken
• Bitfinex

ATOM-USD

• Binance
• OKEx
• Huobi
• CoinbasePro
• Kraken

COMP-USD

• Binance
• CoinbasePro
• OKEx
• Huobi
• FTX
• Kraken

LTC-USD

• Binance
• Huobi
• CoinbasePro
• FTX
• Kraken
• OKEx

EOS-USD

• Binance
• Huobi
• OKEx
• CoinbasePro
• Bitfinex
• kraken

BCH-USD

• OKEx
• Binance
• Huobi
• CoinbasePro
• Kraken
• FTX
• Gemini

XMR-USD

• Binance
• OKEx
• Huobi
• Kraken
• Bitfinex

Implementation Details

Reaching Final Price

Each individual exchange price is the median of best_bid, best_ask, last_price.

Price conversions

For exchanges with greater Token-USDT liquidity we then divide that by our index price for USDT-USDC.

Clients

Python and TypeScript clients are available, allowing programmatic usage of dYdX.

Python Client

Installation

Install dydx-v3-python from PyPI using pip:

pip install dydx-v3-python

Usage

See dydxprotocol/dydx-v3-python.

See the examples folder for simple python examples.

TypeScript Client

Installation

Install @dydxprotocol/v3-client from NPM:

npm i -s @dydxprotocol/v3-client

Usage

See dydxprotocol/v3-client.

See the examples folder for simple typescript examples.

Client Initialization

Initialize

client = Client(
    host='https://api.dydx.exchange',
    web3=Web3('...'),
    stark_private_key='01234abcd...',
)

const client: DydxClient = new Client(
    'host',
    {
        apiTimeout: 3000,
        starkPrivateKey: '01234abcd...',
    },
);

The client is organized into modules, based on the type of authentication needed for different requests. The configuration options passed into the client determine which modules are available. See Authentication for more information.

The following configuration options are available:

C++ Methods for Faster STARK Signing

The C++ wrapper methods in the client expect an absolute path to a Shared Object. This has to be compiled from Starkware's crypto C++ library.

Private HTTP API

Authentication

There are three levels of authentication to be considered when using dYdX. All signing can be handled directly by the client libraries.

Ethereum Key Authentication

The highest level of authentication is via an account's Ethereum private key. The Ethereum key remains in control of an account's funds while they are within the L2 system. This includes the ability to forcibly close an account's positions and exit the system, in the event that the L2 operators (dYdX and Starkware) were to unexpectedly go offline or otherwise censor requests.

Ethereum key authentication is required for the following operations:

• Register a new user or STARK key
• Create or revoke API keys
• Request a forced withdrawal or forced trade

STARK Key Authentication

Within the L2 system, authentication is handled by a separate key pair, known as the account's STARK key pair.

STARK key authentication is required for the following operations:

• Place an order
• Withdraw funds

API Key Authentication

The third level of authentication consists of the API key, secret and passphrase which are used solely to authenticate API requests made to dYdX. This includes operations such as canceling orders or retrieving an account's fills, which do not affect the L2 system.

When a user onboards via POST v3/onboarding, the server will use the signature as a seed to determinstically generate default API key credentials. An API key includes three fields:

• key: UUID identifying the credentials.
• secret: Secret string used to generate HMACs, not sent with requests.
• passphrase: Secret string sent with each request, used to encrypt/decrypt the secret in our DB, and never stored in our DB.

API keys can be added and managed via the /v3/api-keys endpoints.

All requests which are not signed by an Ethereum key and which are made to private endpoints require an API key signature.

STARK Key Cryptography

The STARK and API keys are ECDSA key pairs on the STARK curve. More info on the cryptography used on L2 is available in Starkware's documentation.

Creating and Signing Requests

Within the private HTTP API, there are three groups of endpoints which each require different headers and authentication.

(Separately, and in addition to the above, STARK signatures are required for orders and withdrawals. For details, please refer to the Python and TypeScript reference implementations.)

Onboarding Endpoint: POST v3/onboarding

Request Headers

Signing

The header DYDX-SIGNATURE is an EIP-712 Ethereum signature on a static message containing the fields:

• action: The string DYDX-ONBOARDING.
• onlySignOn: The string https://trade.dydx.exchange.

See reference implementations: [Python] [TypeScript]

Ethereum Key Private Endpoints

This group includes the POST and DELETE v3/api-keys endpoints for managing API keys. Like the onboarding endpoint, requests to these endpoints require signatures by the user's Ethereum key.

Request Headers

Signing

The header DYDX-SIGNATURE is an EIP-712-compliant Ethereum signature on a message containing the fields:

• method: The name of the HTTP method used, uppercase (e.g. GET).
• requestPath: The API endpoint path, beginning with /v3/.
• body: The HTTP request body (normally empty for GET and DELETE).
• timestamp: Equal to the header DYDX-TIMESTAMP.

See reference implementations: [Python] [TypeScript]

API Key Private Endpoints

All private endpoints not listed above fall in this category, and must be authenticated via an API key.

Request Headers

Signing

The DYDX-SIGNATURE is a SHA-256 HMAC produced as described below, and encoded as a Base64 string.

A SHA-256 HMAC is created using the API key secret and the message timestamp + method + requestPath + body defined as follows:

• timestamp: The DYDX-TIMESTAMP header, which must be within 30 seconds of the server time.
• method: The name of the HTTP method used, uppercase (e.g. GET).
• requestPath: The API endpoint path, beginning with /v3/.
• body: The HTTP request body (normally empty for GET and DELETE).

The HMAC should be encoded as a Base64 string and sent as the DYDX-SIGNATURE header.

See reference implementations: [Python] [TypeScript]

Onboarding

Overview

A few steps are required of all accounts before they can begin trading:

1. Create a user, providing a STARK public key to be associated with the main account.
2. Request registration signature from dYdX.
3. Send registration request to the L1 smart contract.
4. Approve collateral token allowance on the L1 smart contract.
5. Deposit collateral token to the L1 smart contract.

All of these steps are supported by the Python and TypeScript clients. See the Python integration tests for an example of onboarding and usage of various endpoints.

Create User

onboarding_information = client.onboarding.create_user(
  # Optional if stark_private_key was provided.
  stark_public_key='012340bcd...',
  stark_public_key_y_coordinate='01234abcd...',
  # Optional if eth_private_key or web3.eth.defaultAccount was provided.
  ethereum_address='ethereumAddress',
)

const onboardingInformation: {
  apiKey: ApiKeyCredentials,
  user: UserResponseObject,
  account: AccountResponseObject,
}  = await client.onboarding.createUser(
  {
    starkKey: '71234abcd...',
    starkKeyYCoordinate: '01234abcd...',
  },
  ethereumAddress: 'ethereumAddress',
);

{
  "apiKey": {
    "key": "290decd9-548b-62a8-d603-45a988386fc8",
    "passphrase": "S6a8lUhACPY2L5MWDvPl",
    "secret": "KQ3s2VSLYqjWA0WpiDhvyEumvJVIQAj2Ni-TFg7z"
  },
  "user": {
    "ethereumAddress": "0x0913017c740260fea4b2c62828a4008ca8b0d6e4",
    "isRegistered": true,
    "email": "[email protected]",
    "username": "supersam15o",
    "referredByAffiliateLink": null,
    "makerFeeRate": "0.01",
    "takerFeeRate": "0.01",
    "makerVolume30D": "1000.00",
    "takerVolume30D": "1000.00",
    "fees30D": "00.50",
    "userData": {},
    "dydxTokenBalance": "0",
    "stakedDydxTokenBalance": "0",
    "isEmailVerified": false,
    "isSharingUsername": null,
    "isSharingAddress": true,
  },
  "account": {
    "starkKey": "180913017c740260fea4b2c62828a4008ca8b0d6e4",
    "positionId": "1812",
    "equity": "10000",
    "freeCollateral": "10000",
    "quoteBalance": "10000",
    "pendingDeposits": "0",
    "pendingWithdrawals": "0",
    "createdAt": "2021-04-09T21:08:34.984Z",
    "openPositions": {
      "BTC-USD": {
        "market": "BTC-USD",
        "status": "OPEN",
        "side": "LONG",
        "size": "1000",
        "maxSize": "1050",
        "entryPrice": "100",
        "exitPrice": null,
        "unrealizedPnl": "50",
        "realizedPnl": "100",
        "createdAt": "2021-01-04T23:44:59.690Z",
        "closedAt": null,
        "netFunding": "500",
        "sumOpen": "1050",
        "sumClose": "50"
      }
    },
    "accountNumber": "5",
    "id": "id"
  }
}

HTTP Request

POST v3/onboarding

Description: Onboard a user so they can begin using dYdX V3 API. This will generate a user, account and derive a key, passphrase and secret from the signature.

Request

Response

Derive StarkKey

Derive StarkKey

key_pair_with_y_coordinate = client.onboarding.derive_stark_key(
  # Optional if eth_private_key or web3.eth.defaultAccount was provided.
  ethereum_address='ethereumAddress',
)

const keyPairWithYCoordinate: KeyPairWithYCoordinate = await client.onboarding.deriveStarkKey(
  'ethereumAddress',
);

Request

Response

KeyPairWithYCoordinate

Recover Default API Credentials

Recover Default API Credentials

api_credentials = client.onboarding.recover_default_api_key_credentials(
  # Optional if eth_private_key or web3.eth.defaultAccount was provided.
  ethereum_address='ethereumAddress',
)

const apiCredentials: ApiKeyCredentials = await client.onboarding.recoverDefaultApiCredentials(
  'ethereumAddress',
);

Request

Response

ApiKeyCredentials

Get Registration

Get Registration

signature = client.private.get_registration()

const signature: { signature: string } = await client.private.getRegistration();

{
  "signature": "foo"
}

HTTP Request

GET v3/registration

Description: Gets the dYdX provided Ethereum signature required to send a registration transaction to the Starkware smart contract.

Response

Register API Key

Register API Key

api_key_response = client.api_keys.create_api_key(
  # Optional if eth_private_key or web3.eth.defaultAccount was provided.
  ethereum_address='0x0123...',
)

const apiKey: { apiKey: ApiKeyCredentials } = await client.apiKeys.createApiKey(
  '0x0123...',
);

{
  "apiKey": {
    "key": "290decd9-548b-62a8-d603-45a988386fc8",
    "passphrase": "S6a8lUhACPY2L5MWDvPl",
    "secret": "KQ3s2VSLYqjWA0WpiDhvyEumvJVIQAj2Ni-TFg7z"
  }
}

HTTP Request

POST v3/api-keys

Description: Create new API key credentials for a user.

Response

Get API Keys

Get API Keys

api_keys = client.private.get_api_keys()

const apiKeys: { keys: string[] } = await client.private.getApiKeys();

{
  "apiKeys": [
    "290decd9-548b-62a8-d603-45a988386fc8",
    "390decd9-548b-62a8-d603-45a988386fc8",
    ...
  ]
}

HTTP Request

GET v3/api-keys

Description: Get all api keys associated with an Ethereum address.

Response

Delete API Key

Delete API Key

client.api_keys.delete_api_key(
  api_key='290decd9-548b-...',
  # Optional if eth_private_key or web3.eth.defaultAccount was provided.
  ethereum_address='0x0123...',
)

await client.apiKeys.delete_api_key(
  '290decd9-548b-...', // API key
  '0x0123...', // Ethereum address
);

{
  "apiKey": "foo"
}

HTTP Request

DELETE v3/api-keys

Description: Delete an api key by key and Ethereum address.

Request

Response

Returns a 200 on success.

Get User

Get User

user = client.private.get_user()

const user: { user: UserResponseObject } = await client.private.getUser();

{
  "user": {
    "ethereumAddress": "0x0913017c740260fea4b2c62828a4008ca8b0d6e4",
    "isRegistered": true,
    "email": "[email protected]",
    "username": "supersam15o",
    "referredByAffiliateLink": null,
    "makerFeeRate": "0.01",
    "takerFeeRate": "0.01",
    "makerVolume30D": "1000.00",
    "takerVolume30D": "1000.00",
    "fees30D": "00.50",
    "userData": {},
    "dydxTokenBalance": "0",
    "stakedDydxTokenBalance": "0",
    "isEmailVerified": false
  }
}

HTTP Request

GET v3/users

Description: return the user and user information.

Response

Update User

Update user

user = client.private.update_user(
  user_data={},
  email='[email protected]',
  username='username',
  is_sharing_email=False,
  is_sharing_address=True,
)

const user: { user: UserResponseObject } = await client.private.updateUser({
  email: '[email protected]',
  username: 'username',
  isSharingEmail: false,
  isSharingAddress: false,
  userData: {},
});

{
  "user": {
    "ethereumAddress": "0x0913017c740260fea4b2c62828a4008ca8b0d6e4",
    "isRegistered": true,
    "email": "[email protected]",
    "username": "supersam15o",
    "referredByAffiliateLink": null,
    "makerFeeRate": "0.01",
    "takerFeeRate": "0.01",
    "makerVolume30D": "1000.00",
    "takerVolume30D": "1000.00",
    "fees30D": "00.50",
    "userData": {},
    "dydxTokenBalance": "0",
    "stakedDydxTokenBalance": "0",
    "isEmailVerified": false
  }
}

HTTP Request

PUT v3/users

Description: Update user information and return the updated user.

Response

Create An Account

Create Account

client.private.create_account(
  stark_public_key='701234abcd...',
  stark_public_key_y_coordinate='1234abcd...',
)

const account: { account: AccountResponseObject } = await client.private.createAccount(
  '701234abcd...', // starkKey
  '1234abcd...', // starkKeyYCoordinate
);

{
  "account": {
    "starkKey": "180913017c740260fea4b2c62828a4008ca8b0d6e4",
    "positionId": "1812",
    "equity": "10000",
    "freeCollateral": "10000",
    "quoteBalance": "10000",
    "pendingDeposits": "0",
    "pendingWithdrawals": "0",
    "createdAt": "2021-04-09T21:08:34.984Z",
    "openPositions": {
      "BTC-USD": {
        "market": "BTC-USD",
        "status": "OPEN",
        "side": "LONG",
        "size": "1000",
        "maxSize": "1050",
        "entryPrice": "100",
        "exitPrice": null,
        "unrealizedPnl": "50",
        "realizedPnl": "100",
        "createdAt": "2021-01-04T23:44:59.690Z",
        "closedAt": null,
        "netFunding": "500",
        "sumOpen": "1050",
        "sumClose": "50"
      }
    },
    "accountNumber": "5",
    "id": "id"
  }
}

HTTP Request

POST v3/accounts

Description: Create an account with a given starkKey.

Request

Response

Get Account

Get Account

account = client.private.get_account(
  # Optional if eth_private_key or web3.eth.defaultAccount was provided.
  ethereum_address='0x0123...',
)

const account: { account: AccountResponseObject } = await client.private.getAccount(
  '0x0123...',
);

{
  "account": {
    "starkKey": "180913017c740260fea4b2c62828a4008ca8b0d6e4",
    "positionId": "1812",
    "equity": "10000",
    "freeCollateral": "10000",
    "quoteBalance": "10000",
    "pendingDeposits": "0",
    "pendingWithdrawals": "0",
    "createdAt": "2021-04-09T21:08:34.984Z",
    "openPositions": {
      "BTC-USD": {
        "market": "BTC-USD",
        "status": "OPEN",
        "side": "LONG",
        "size": "1000",
        "maxSize": "1050",
        "entryPrice": "100",
        "exitPrice": null,
        "unrealizedPnl": "50",
        "realizedPnl": "100",
        "createdAt": "2021-01-04T23:44:59.690Z",
        "closedAt": null,
        "netFunding": "500",
        "sumOpen": "1050",
        "sumClose": "50"
      }
    },
    "accountNumber": "5",
    "id": "id"
  }
}

HTTP Request

GET v3/accounts/:id

Description: Get an account for a user by id. Using the client, the id will be generated with client information and an Ethereum address.

Request

Response

Get Account Leaderboard PNLs

Get Account Leaderboard PNLs

const account: { accountPnls: AccountLeaderboardPnlResponseObject } = await client.private.getAccountLeaderboardPnl(
  period=LeaderboardPnlPeriod.DAILY,
);

{
  "absolutePnl": "100.000000",
  "percentPnl": "100.000000",
  "absoluteRank": 10,
  "percentRank": 10,
  "updatedAt": "2021-08-02T22:53:45.659Z",
  "accountId": "afoo",
}

HTTP Request

GET v3/accounts/leaderboard-pnl/:period

Description: Get an account's personal leaderboard pnls.

Request

Response

Get Accounts

Get Account

accounts = client.private.get_accounts()

const accounts: { accounts: AccountResponseObject[] } = await client.private.getAccounts();

{ "accounts": [{
    "starkKey": "180913017c740260fea4b2c62828a4008ca8b0d6e4",
    "positionId": "1812",
    "equity": "10000",
    "freeCollateral": "10000",
    "quoteBalance": "10000",
    "pendingDeposits": "0",
    "pendingWithdrawals": "0",
    "createdAt": "2021-04-09T21:08:34.984Z",
    "openPositions": {
      "BTC-USD": {
        "market": "BTC-USD",
        "status": "OPEN",
        "side": "LONG",
        "size": "1000",
        "maxSize": "1050",
        "entryPrice": "100",
        "exitPrice": null,
        "unrealizedPnl": "50",
        "realizedPnl": "100",
        "createdAt": "2021-01-04T23:44:59.690Z",
        "closedAt": null,
        "netFunding": "500",
        "sumOpen": "1050",
        "sumClose": "50"
      }
    },
    "accountNumber": "5",
    "id": "id"
  }]
}

HTTP Request

GET v3/accounts

Description: Get all accounts for a user.

Response

Get Positions

Get Positions

from dydx3.constants import MARKET_BTC_USD
from dydx3.constants import POSITION_STATUS_OPEN

all_positions = client.private.get_positions(
  market=MARKET_BTC_USD,
  status=POSITION_STATUS_OPEN,
)

const positions: { positions: PositionResponseObject[] } = await client.private.getPositions(
  {
    market: Market.BTC_USD,
    status: PositionStatus.OPEN,
  },
);

{
  "market": "BTC-USD",
  "status": "OPEN",
  "side": "LONG",
  "size": "1000",
  "maxSize": "1050",
  "entryPrice": "100",
  "exitPrice": null,
  "unrealizedPnl": "50",
  "realizedPnl": "100",
  "createdAt": "2021-01-04T23:44:59.690Z",
  "closedAt": null,
  "netFunding": "500",
  "sumOpen": "1050",
  "sumClose": "50"
}

HTTP Request

GET v3/positions

Description: Get all current positions for a user by specified query parameters.

For each market, a position is created with status=OPEN. A position is set to status=CLOSED when it goes to market-neutral (i.e. size=0). On a per-market basis, there should be at most one status=OPEN position at any given time.

Request

Response

Get Transfers

Get Transfers

from dydx3.constants import ACCOUNT_ACTION_DEPOSIT

transfers = client.private.get_transfers(
  transfer_type=ACCOUNT_ACTION_DEPOSIT,
  limit=50,
)

const transfers: { transfers: TransferResponseObject[] } = await client.private.getTransfers(
  {
    type: AccountAction.DEPOSIT,
    limit: 50,
  },
);

{
  "transfers": [{
    "id": "foo",
    "type": "DEPOSIT",
    "debitAsset": "USDC",
    "creditAsset": "USDT",
    "debitAmount": "3000",
    "creditAmount": "2800",
    "transactionHash": "hash",
    "status": "PENDING",
    "createdAt": "2021-01-04T23:44:59.690Z",
    "confirmedAt": null,
    "clientId": "foo",
    "fromAddress": "0x0913017c740260fea4b2c62828a4008ca8b0d6e4",
    "toAddress": null
  }]
}

HTTP Request

GET v3/transfers

Description: Get transfers for a user, limited by query parameters.

Request

Response

Fast vs. Slow Withdrawal

The normal process for withdrawing from L2 to L1 requires waiting for a block of L2 transactions to be collected, and the zero-knowledge proof for the block to be constructed and verified on-chain.

Using the fast withdrawal process, users can get their funds on L1 much faster by essentially trading their L2 funds to an “LP” account operated by dYdX, in order to receive immediate liquidity on L1. Since the LP must then recycle these funds from L2 to L1 via the regular withdrawal process, dYdX is only able to process a certain volume of fast withdrawals within a given period of time.

Create Withdrawal

Create Withdrawal

from dydx3.constants import ASSET_USDC

withdrawal = client.private.create_withdrawal(
  position_id=1, # required for creating the withdrawal signature
  amount='100',
  asset=ASSET_USDC,
  expiration_epoch_seconds=1613988637,
)

const withdrawal: { withdrawal: TransferResponseObject } = await client.private.createWithdrawal(
  {
    amount: '100',
    asset: Asset.USDC,
    expiration: '2020-12-28T22:49:31.588Z',
  },
  '1', // positionId required for creating the withdrawal signature
);

{
  "withdrawal": {
    "id": "foo",
    "type": "WITHDRAWAL",
    "debitAsset": "USDC",
    "creditAsset": "USDC",
    "debitAmount": "3000",
    "creditAmount": "2800",
    "transactionHash": "hash",
    "status": "PENDING",
    "createdAt": "2021-01-04T23:44:59.690Z",
    "confirmedAt": null,
    "clientId": "foo",
    "fromAddress": "0x0913017c740260fea4b2c62828a4008ca8b0d6e4",
    "toAddress": null
  }
}

HTTP Request

POST v3/withdrawals

Description: Create a withdrawal from an account.

Request

Response

Create Fast Withdrawal

Create Fast Withdrawal

from dydx3.constants import ASSET_USDC

fast_withdrawal = client.private.create_fast_withdrawal(
  position_id='1', # required for creating the fast-withdrawal signature
  credit_asset=ASSET_USDC,
  credit_amount='100',
  debit_amount='110',
  to_address='0x98ab...',
  lp_position_id='2',
  expiration_epoch_seconds=1613988637,
  signature='0abc12...',  # Optional if stark_private_key was provided to client.
)

const fastWithdrawal: { withdrawal: TransferResponseObject } = await client.private.createFastWithdrawal(
  {
    creditAsset: Asset.USDC,
    creditAmount: '100',
    debitAmount: '110',
    toAddress: '0x98ab...',
    lpPositionId: '2',
    clientId: 'client',
    signature: '0abc12...', // Optional if starkPrivateKey was provided to client.
  },
  '1', // positionId required for creating the fast-withdrawal signature
);

{
  "withdrawal": {
    "id": "foo",
    "type": "FAST_WITHDRAWAL",
    "debitAsset": "USDC",
    "creditAsset": "USDC",
    "debitAmount": "3000",
    "creditAmount": "2800",
    "transactionHash": "hash",
    "status": "PENDING",
    "createdAt": "2021-01-04T23:44:59.690Z",
    "confirmedAt": null,
    "clientId": "foo",
    "fromAddress": "0x0913017c740260fea4b2c62828a4008ca8b0d6e4",
    "toAddress": null
  }
}

HTTP Request

POST v3/fast-withdrawals

Description: Create a fast-wthdrawal.

Request

Response

Order Types

Create A New Order

Create Order

from dydx3.constants import MARKET_BTC_USD
from dydx3.constants import ORDER_SIDE_SELL
from dydx3.constants import ORDER_TYPE_LIMIT
from dydx3.constants import TIME_IN_FORCE_GTT

placed_order = client.private.create_order(
  position_id=1, # required for creating the order signature
  market=MARKET_BTC_USD,
  side=ORDER_SIDE_SELL,
  order_type=ORDER_TYPE_LIMIT,
  post_only=False,
  size='100',
  price='18000',
  limit_fee='0.015',
  expiration_epoch_seconds=1613988637,
  time_in_force=TIME_IN_FORCE_GTT,
)

const order: { order: OrderResponseObject } = await client.private.createOrder(
  {
    side: OrderSide.SELL,
    type: OrderType.LIMIT,
    timeInForce: TimeInForce.GTT,
    postOnly: false,
    size: '100',
    price: '18000',
    limitFee: '0.015',
    expiration: '2022-12-21T21:30:20.200Z',
  },
  '1', // required for creating the order signature
);

{
  "order": {
    "id": "foo",
    "clientId": "foo",
    "accountId": "afoo",
    "market": "BTC-USD",
    "side": "SELL",
    "price": "18000",
    "triggerPrice": null,
    "trailingPercent": null,
    "size": "100",
    "remainingSize": "100",
    "type": "LIMIT",
    "createdAt": "2021-01-04T23:44:59.690Z",
    "unfillableAt": null,
    "expiresAt": "2022-12-21T21:30:20.200Z",
    "status": "PENDING",
    "timeInForce": "GTT",
    "postOnly": false,
    "cancelReason": null
  }
}

HTTP Request

POST v3/orders

Description: Create a new order.

Request

Response

Order LimitFee

The limitFee is the highest fee a user would be willing to accept on an order. This should be in decimal form (i.e. 0.1 is 10%). To see current fees, call GET /v3/users and the maker/taker fee rates show what fees will be. If the order is postOnly dYdX will validate against makerFeeRate only. The opposite is true if the order is FOK or IOC - dYdX will only validate against takerFeeRate. Otherwise, dYdX assesses against the maximum of maker and taker fee rate.

Tick Size and Minimum Size

Tick Size

Each market has a specified tickSize. Order price must be a multiple of the tickSize. THe same applies to triggerPrice and trailingPercent if either of these are not null.

Minimum Size

Each market has a specified minOrderSize. Order size must be not be less than the minOrderSize.

Order Deletion

Canceled orders older than one month are deleted from the dYdX database.

Cancel An Order

Cancel an order

client.private.cancel_order(order_id='0x0000')

await client.private.cancelOrder('0x0000');

{}

HTTP Request

DELETE v3/orders/:id

Description: Cancel an order by its unique id.

Request

Response

Cancel Orders

Cancel orders

from dydx3.constants import MARKET_BTC_USD

client.private.cancel_all_orders(market=MARKET_BTC_USD)

await client.private.cancelAllOrders(Market.BTC_USD);

{}

HTTP Request

DELETE v3/orders

Description: Either bulk cancel all orders or just all orders for a specific market.

Request

Response

Get Orders

Get Orders

from dydx3.constants import MARKET_BTC_USD
from dydx3.constants import ORDER_SIDE_SELL
from dydx3.constants import ORDER_TYPE_LIMIT
from dydx3.constants import ORDER_STATUS_OPEN

all_orders = client.private.get_orders(
  market=MARKET_BTC_USD,
  status=ORDER_STATUS_OPEN,
  side=ORDER_SIDE_SELL,
  type=ORDER_TYPE_LIMIT,
  limit=50,
)

const allOrders: { orders: OrderResponseObject[] } = await client.private.getOrders(
  {
    market: Market.BTC_USD,
    status: OrderStatus.OPEN,
    side: OrderSide.SELL,
    type: OrderType.LIMIT,
    limit: 50,
  },
);

{
  "orders": [
    {
      "id": "id",
      "clientId": "foo",
      "accountId": "afoo",
      "market": "BTC-USD",
      "side": "SELL",
      "price": "29000",
      "triggerPrice": null,
      "trailingPercent": null,
      "size": "0.500",
      "remainingSize": "0.500",
      "type": "LIMIT",
      "createdAt": "2021-01-04T23:44:59.690Z",
      "unfillableAt": null,
      "expiresAt": "2021-02-04T23:44:59.690Z",
      "status": "OPEN",
      "timeInForce": "GTT",
      "postOnly": false,
      "cancelReason": null
    },
    ...
  ]
}

HTTP Request

GET v3/orders

Description: Get active (not filled or canceled) orders for a user by specified parameters.

Request

Response

Order

Order Statuses

Cancel Reasons

Get Order By Id

Get Order By Id

order = client.private.get_order_by_id('foo')

const orderResponse: { order: OrderResponseObject } = await client.private.getOrderById('foo');

{
  "order": {
    "id": "foo",
    "clientId": "foo",
    "accountId": "afoo",
    "market": "BTC-USD",
    "side": "SELL",
    "price": "29000",
    "triggerPrice": null,
    "trailingPercent": null,
    "size": "0.500",
    "remainingSize": "0.500",
    "type": "LIMIT",
    "createdAt": "2021-01-04T23:44:59.690Z",
    "unfillableAt": null,
    "expiresAt": "2021-02-04T23:44:59.690Z",
    "status": "OPEN",
    "timeInForce": "GTT",
    "postOnly": false,
    "cancelReason": null
  }
}

HTTP Request

GET v3/orders/:id

Description: Get an order by id from the active orderbook and order history.

Request

Response

Get Order by ClientId

Get Order By ClientId

order = client.private.get_order_by_client_id('clientId')

const allOrders: { order: OrderResponseObject } = await client.private.getOrderByClientId('clientId');

{
  "order": {
    "id": "foo",
    "clientId": "foo",
    "accountId": "afoo",
    "market": "BTC-USD",
    "side": "SELL",
    "price": "29000",
    "triggerPrice": null,
    "trailingPercent": null,
    "size": "0.500",
    "remainingSize": "0.500",
    "type": "LIMIT",
    "createdAt": "2021-01-04T23:44:59.690Z",
    "unfillableAt": null,
    "expiresAt": "2021-02-04T23:44:59.690Z",
    "status": "OPEN",
    "timeInForce": "GTT",
    "postOnly": false,
    "cancelReason": null
  }
}

HTTP Request

GET v3/orders/client/:id

Description: Get an order by clientId from the active orderbook and order history.

Request

Response

Get Fills

Get Fills

from dydx3.constants import MARKET_BTC_USD

all_fills = client.private.get_fills(
  market=MARKET_BTC_USD,
)

const allFills: { fills: FillResponseObject[] } = await client.private.getFills(
  {
    market: Market.BTC_USD,
  },
);

{
  "fills": [
    {
      "id": "foo",
      "side": "BUY",
      "liquidity": "TAKER",
      "type": "LIMIT",
      "market": "BTC-USD",
      "orderId": "id",
      "price": "29000",
      "size": "0.001",
      "fee": "100",
      "createdAt": "2021-01-05T16:33:43.163Z"
    },
    ...
  ]
}

HTTP Request

GET v3/fills

Description: Get Fills for a user by specified parameters.

Request

Response

Fill

Get Funding Payments

Get Funding Payments

from dydx3.constants import MARKET_BTC_USD

funding_payments = client.private.get_funding_payments(
  market=MARKET_BTC_USD,
  limit=75,
)

const fundingPayments: { fundingPayments: FundingResponseObject } = await client.private.getFundingPayments(
  {
    market: Market.BTC_USD,
    limit: 75,
  },
);

{
  "fundingPayments": [{
    "market": "BTC-USD",
    "payment": "10000",
    "rate": "0.0000125000",
    "positionSize": "500",
    "price": "90",
    "effectiveAt": "2021-01-04T23:44:59.690Z"
  }]
}

HTTP Request

GET v3/funding

Description: Get Funding Payments made to an account.

Request

Response

Get Historical PNL Ticks

Get Historical PNL Ticks

historical_pnl = client.private.get_historical_pnl(
  created_before_or_at='2021-04-09T22:02:46+0000',
)

const historicalPnlTicks: {
  historicalPnl: HistoricalPnlResponseObject[],
} = await client.private.getHistoricalPnl(
  {
    createdBeforeOrAt: '2021-04-09T22:02:46+0000',
  },
);

{
  "historicalPnl": [{
    "equity": "0.0000",
    "totalPnl": "0.0000",
    "createdAt": "2021-04-09T21:08:34.984Z",
    "netTransfers": "0.0000",
    "accountId": "49979004..."
  }]
}

HTTP Request

GET v3/historical-pnl

Description: Get Historical PNL for an account during an interval.

Request

Response

HistoricalAggregatedPnl

Get Trading Rewards

Get Trading Rewards

rewards = client.private.get_trading_rewards(
  epoch=0,
)

const rewards: {
  tradingRewards: TradingRewardsResponseObject,
} = await client.private.getTradingRewards(
  {
    epoch: 0,
  },
);

{
  "epoch": 0,
  "epochStart": "2021-08-03T15:00:00.000Z",
  "epochEnd": "2021-08-31T15:00:00.000Z",
  "fees": {
    "feesPaid": "0",
    "totalFeesPaid": "0"
  },
  "openInterest": {
    "averageOpenInterest": "0",
    "totalAverageOpenInterest": "0"
  },
  "weight": {
    "weight": "0",
    "totalWeight": "0"
  },
  "totalRewards": "0",
  "estimatedRewards": "0"
}

HTTP Request

GET v3/rewards/weight

Description: Get the rewards weight of a given epoch.

Request

Response

Weight

Fees

OpenInterest

Get Liquidity Provider Rewards

Get Liquidity Provider Rewards

rewards = client.private.get_liquidity_provider_rewards(
  epoch=0,
)

const rewards: {
  liquidityRewards: LiquidityProviderRewardsResponseObject,
} = await client.private.getLiquidityProviderRewards(
  {
    epoch: 0,
  },
);

{
  "epoch": 0,
  "epochStart": "2021-08-03T15:00:00.000Z",
  "epochEnd": "2021-08-31T15:00:00.000Z",
  "markets": {
    "BTC-USD": {
      "market": "BTC-USD",
      "uptime": "0.75",
      "score": "100",
      "totalScore": "1000",
      "totalRewards": "1000",
      "estimatedRewards": "100",
    }
    ...
  },
}

HTTP Request

GET v3/rewards/liquidity

Description: Get the liquidity rewards of a given epoch.

Request

Response

LiquidityRewards

Get Retroactive Mining Rewards

Get Retroactive Mining Rewards

rewards = client.private.get_retroactive_mining_rewards()

const rewards: {
  retroactiveMiningRewards: RetroactiveMiningRewardsResponseObject,
} = await client.private.getRetroactiveMiningRewards();

{
  "epoch": 0,
  "epochStart": "2021-08-03T15:00:00.000Z",
  "epochEnd": "2021-08-31T15:00:00.000Z",
  "retroactiveMining": {
    "allocation": "1000",
    "targetVolume": "500",
    "volume": "100"
  },
  "estimatedRewards": "500"
}

HTTP Request

GET v3/rewards/retroactive-mining

Description: Get the retroactive mining rewards of a given epoch.

Response

RetroactiveMiningRewards

Send Verification Email

Send a verification email

client.private.send_verification_email()

await client.private.sendVerificationEmail();

{}

HTTP Request

PUT v3/emails/send-verification-email

Description: Send an email to the email address associated with the user, requesting that they click on a link to verify their email address.

Response

On success, returns a 204 response with an empty body. Responds with a 400 error if no email address is on file for the user, or their email address has already been verified.

Setting Notification Status

In addition to verifying an email, notifications must be set in user.userData to start receiving emails per category.

Example userData:

user.userData = {
  notifications: {
    deposit: {
      email: true
    },
    trades: {
      email: true
    }
  }
}

Public HTTP API

Get Markets

Get Markets

markets = client.public.get_markets()

const markets: { markets: MarketsResponseObject } = await client.public.getMarkets();

{
  "markets": {
    "LINK-USD": {
    "market": "LINK-USD",
    "status": "ONLINE",
    "baseAsset": "LINK",
    "quoteAsset": "USD",
    "stepSize": "0.1",
    "tickSize": "0.01",
    "indexPrice": "12",
    "oraclePrice": "101",
    "priceChange24H": "0",
    "nextFundingRate": "0.0000125000",
    "nextFundingAt": "2021-03-01T18:00:00.000Z",
    "minOrderSize": "1",
    "type": "PERPETUAL",
    "initialMarginFraction": "0.10",
    "maintenanceMarginFraction": "0.05",
    "baselinePositionSize": "1000",
    "incrementalPositionSize": "1000",
    "incrementalInitialMarginFraction": "0.2",
    "volume24H": "0",
    "trades24H": "0",
    "openInterest": "0",
    "maxPositionSize": "10000",
    "assetResolution": "10000000"
  },
  ...
}

HTTP Request

GET v3/markets

Description: Get one or all markets as well as metadata about each retrieved market.

Request

Response

Market

Get Orderbook

Get Trades

from dydx3.constants import MARKET_BTC_USD

orderbook = client.public.get_orderbook(
  market=MARKET_BTC_USD,
)

const orderbook: OrderbookResponseObject = await client.public.getOrderbook(
  Market.BTC_USD,
);

{
  "bids": [
    {
      "price": "29000",
      "size": "1"
    },
    ...
  ],
  "asks": [
    {
      "price": "29500",
      "size": "0.499"
    },
    ...
  ]
}

HTTP Request

GET v3/orderbook/:market

Description: Returns the active orderbook for a market. All bids and asks that are fillable are returned.

Request

Response

Orderbook Order

Get Trades

Get Trades

from dydx3.constants import MARKET_BTC_USD

all_trades = client.public.get_trades(
  market=MARKET_BTC_USD,
)

const trades: { trades: Trade[] } = await client.public.getTrades({
  market: Market.BTC_USD,
  startingBeforeOrAt: "2021-01-05T17:33:43.163Z",
  limit: 1,
});

{
  "trades": [
    {
      "side": "BUY",
      "size": "0.001",
      "price": "29000",
      "createdAt": "2021-01-05T16:33:43.163Z"
    },
    ...
  ]
}

HTTP Request

GET v3/trades/:market

Description: Get Trades by specified parameters. Passing in all query parameters to the HTTP endpoint would look like: GET v3/trades/BTC-USD?startingBeforeOrAt=2021-09-05T17:33:43.163Z&limit=1.

Request

Response

Trade

Get Fast Withdrawal Liquidity

Get Fast Withdrawal

fast_withdrawals_info = client.public.get_fast_withdrawal()

const availableFundsMap: {
  liquidityProviders: {
    [positionId: string]: {
      availableFunds: string,
      starkKey: string,
      quote: {
        creditAsset: string,
        creditAmount: string,
        debitAmount: string,
      } | null,
    }
  }
} = await client.public.getFastWithdrawalAvailableFunds();

{
  "liquidityProviders": {
    "1812": {
      "availableFunds": "1000",
      "starkKey": "180913017c740260fea4b2c62828a4008ca8b0d6e4",
      "quote": null,
    },
  }
}

HTTP Request

GET v3/fast-withdrawals

Description: Returns a map of all LP provider accounts that have available funds for fast withdrawals. Given a debitAmount and asset the user wants sent to L1, this endpoint also returns the predicted amount of the desired asset the user will be credited on L1. Given a creditAmount and asset the user wants sent to L1, this endpoint also returns the predicted amount the user will be debited on L2.

Request

Response

Liquidity Provider

Liquidity Provider Quote

Get Market Stats

Get Market Stats

from dydx3.constants import MARKET_BTC_USD

market_statistics = client.public.get_stats(
  market=MARKET_BTC_USD,
  days=MARKET_STATISTIC_DAY_SEVEN,
)

const marketStatistics = await client.public.getStats({
  market: Market.BTC_USD,
  days: MarketStatisticDay.SEVEN,
});

{
  "markets": {
    "ETH-USD": {
      "market": "ETH-USD",
      "open": "1100",
      "close": "1100",
      "high": "1100",
      "low": "1095",
      "baseVolume": "10000",
      "quoteVolume": "100000",
      "type": "PERPETUAL",
      "fees": "1000"
    }
  }
}

HTTP Request

GET v3/stats/:market

Description: Get an individual market's statistics over a set period of time or all available periods of time.

Request

Response

MarketStats

Get Historical Funding

Get Historical Funding

from dydx3.constants import MARKET_BTC_USD

historical_funding = client.public.get_historical_funding(
  market=MARKET_BTC_USD,
)

const historicalFunding = await client.public.getHistoricalFunding({
  market: Market.BTC_USD,
});

{
  "historicalFunding": [
    {
      "market": "BTC-USD",
      "rate": "0.0000125000",
      "price": "31297.5000008009374142",
      "effectiveAt": "2021-01-05T09:10:49.000Z"
    },
    ...
  ]
}

HTTP Request

GET v3/historical-funding/:market

Description: Get the historical funding rates for a market.

Request

Response

Historical Funding

Get Candles for Market

Get Candles for Market

from dydx3.constants import MARKET_BTC_USD

candles = client.public.get_candles(
  market=MARKET_BTC_USD,
  resolution='1DAY',
)

const candles: {
  candles: CandleResponseObject,
} = await client.public.getCandles({
  market: Market.BTC_USD,
  resolution: CandleResolution.1DAY,
})

  "candles": [
    {
      "startedAt": "2021-01-05T00:00:00.000Z",
      "updatedAt": "2021-01-05T00:00:00.000Z",
      "market": "BTC-USD",
      "resolution": "1DAY",
      "low": "40000",
      "high": "45000",
      "open": "45000",
      "close": "40000",
      "baseTokenVolume": "1.002",
      "trades": "3",
      "usdVolume": "45085",
      "startingOpenInterest": "28"
    },
    ...
  ]

HTTP Request

GET v3/candles/:market

Description: Get the candle statistics for a market.

Request

Response

Get Global Configuration Variables

HTTP Request

GET v3/config

Description: Get any global configuration variables for the exchange as a whole.

Response

cancelOrderRateLimiting

placeOrderRateLimiting

Check If User Exists

Check If User Exists

user_exists = client.public.check_if_user_exists(
  ethereum_address='foo',
)

const userExists: { exists: boolean } = await client.public.doesUserExistWithAddress(
  'foo',
);

{
  "exists": true
}

HTTP Request

GET v3/users/exists

Description: Check if a user exists for a given Ethereum address.

Request

Response

Check If Username Exists

Check If User Exists

username_exists = client.public.check_if_username_exists(
  username='username',
)

const usernameExists: { exists: boolean } = await client.public.doesUserExistWithUsername(
  'username',
);

{
  "exists": true
}

HTTP Request

GET v3/usernames

Description: Check if a username has been taken by a user.

Request