API reference · v5

dYdX API

dYdX v4 by address: equity, PnL and equity charts, open positions including isolated ones, closed positions, orders and transfers.

Base URL https://api.kopyon.com/v5/dydx/ · send your key in the X-API-KEY header · trader id: A dYdX address (dydx1…).

Get a free API key · Interactive reference with Try it · Authentication, paging and errors

Trader profile

GET /v5/dydx/traderProfile

The address's equity and free collateral across its subaccounts. dYdX has no leaderboard, names or follower counts.

Query parameters

Name	Type	Description
`traderId`required	string	A dYdX address (dydx1...)

Response fields, in `data`

Field	Type	Description
`traderId`always	string
`sourceDetails.equity`	only dYdX
`sourceDetails.freeCollateral`	only dYdX
`sourceDetails.openPositions`	only dYdX
`sourceDetails.subaccounts`	only dYdX

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/dydx/traderProfile?traderId=dydx1000qkj0ns34zk9706plzq4vk07kmgvkdaruddj"

{
  "data": {
    "traderId": "dydx1000qkj0ns34zk9706plzq4vk07kmgvkdaruddj",
    "sourceDetails": {
      "equity": 1639.497175037,
      "freeCollateral": 1616.4667255687,
      "openPositions": 2,
      "subaccounts": 1
    }
  }
}

Trader chart

GET /v5/dydx/traderChart

Hourly all-time PnL or equity over the period, oldest first.

Query parameters

Name	Type	Description
`traderId`required	string	A dYdX address (dydx1...)
`period`required	enum	Days back from now1D, 7D, 30D
`metric`	enumdefault pnl	All-time PnL or equity, in USDCpnl, equity

Response fields, in `data`

Field	Type	Description
`metric`always	string	What the points measure: ROI, PNL or BALANCE
`points[]`always	array
`points[].timestamp`always	number	Point time, in Unix milliseconds
`points[].value`always	number

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/dydx/traderChart?traderId=dydx1000qkj0ns34zk9706plzq4vk07kmgvkdaruddj&period=1D"

{
  "data": {
    "metric": "PNL",
    "points": [
      {
        "timestamp": 1792252893509,
        "value": 696.516078
      },
      {
        "timestamp": 1792256468148,
        "value": 697.894377
      },
      {
        "timestamp": 1792260053544,
        "value": 696.755782
      }
    ]
  }
}

Open positions

GET /v5/dydx/openPositions

Open perpetual positions in every subaccount, cross and isolated, marked at dYdX's oracle price.

dYdX refreshes this dYdX's indexer updates these positions every 5 s..

Query parameters

Name	Type	Description
`traderId`required	string	A dYdX address (dydx1...)

Response fields, in `data`

Field	Type	Description
`positions[]`always	array
`positions[].symbol`always	string
`positions[].side`always	LONG \| SHORT
`positions[].size`	number	Position size, always positive; side gives the direction
`positions[].entryPrice`always	number
`positions[].markPrice`	number	The exchange's mark price
`positions[].marginMode`	ISOLATED \| CROSS
`positions[].unrealizedPnl`	number	In pnlCurrency
`positions[].pnlCurrency`	string
`positions[].liquidationPrice`	number
`positions[].sourceDetails.subaccountNumber`	only dYdX
`positions[].sourceDetails.realizedPnl`	only dYdX
`positions[].openedAt`	number
`positions[].fundingPnl`	number

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/dydx/openPositions?traderId=dydx1000qkj0ns34zk9706plzq4vk07kmgvkdaruddj"

{
  "data": {
    "positions": [
      {
        "symbol": "APEUSD",
        "side": "SHORT",
        "size": 82,
        "entryPrice": 0.607,
        "markPrice": 0.13637496,
        "marginMode": "CROSS",
        "unrealizedPnl": 38.59125328,
        "pnlCurrency": "USDC",
        "openedAt": 1751225227428,
        "fundingPnl": 0.041164,
        "sourceDetails": {
          "subaccountNumber": 0,
          "realizedPnl": 0
        }
      },
      {
        "symbol": "WIFUSD",
        "side": "SHORT",
        "size": 1081,
        "entryPrice": 0.811,
        "markPrice": 0.192358003,
        "marginMode": "CROSS",
        "unrealizedPnl": 668.751998757,
        "pnlCurrency": "USDC",
        "openedAt": 1751131423874,
        "fundingPnl": -3.595406,
        "sourceDetails": {
          "subaccountNumber": 0,
          "realizedPnl": 0
        }
      }
    ]
  }
}

Position history

GET /v5/dydx/positionHistory

Closed positions, newest first, with funding and, when the whole position closed, the gross PnL worked out from the average prices. Fees are in orderHistory.

Query parameters

Name	Type	Description
`traderId`required	string	A dYdX address (dydx1...)
`cursor`	string	The nextCursor of the previous answer; leave it out for the first page
`rows`	intdefault 20	Rows per page1 to 100

Response fields, in `data`

Field	Type	Description
`positions[]`always	array
`positions[].positionId`	string
`positions[].symbol`always	string
`positions[].side`	LONG \| SHORT
`positions[].status`	string
`positions[].marginMode`	ISOLATED \| CROSS
`positions[].leverage`	number
`positions[].roi`	number
`positions[].entryPrice`	number
`positions[].closePrice`	number
`positions[].openedAt`always	number	When the position opened, in Unix milliseconds
`positions[].closedAt`	number	When the position closed, in Unix milliseconds
`positions[].updatedAt`always	number	Last change, in Unix milliseconds
`positions[].openedVolume`	number
`positions[].closedVolume`	number
`positions[].maxOpenInterest`	number
`positions[].grossPnl`	number
`positions[].fundingPnl`	number
`positions[].tradingFee`	number
`positions[].liquidationFee`	number
`positions[].netPnl`	number
`positions[].pnlCurrency`	string
`positions[].sourceDetails.subaccountNumber`	only dYdX
`nextCursor`	string	Send it back as cursor, with the same query, to read the next page; absent on the last page

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/dydx/positionHistory?traderId=dydx1000qkj0ns34zk9706plzq4vk07kmgvkdaruddj"

{
  "data": {
    "positions": []
  }
}

Transfer history

GET /v5/dydx/transferHistory

Deposits, withdrawals and transfers to or from other addresses, newest first. Moves between the address's own subaccounts are left out, so a page can hold fewer rows than asked.

Query parameters

Name	Type	Description
`traderId`required	string	A dYdX address (dydx1...)
`cursor`	string	The nextCursor of the previous answer; leave it out for the first page
`rows`	intdefault 20	Rows per page1 to 100

Response fields, in `data`

Field	Type	Description
`transfers[]`always	array
`transfers[].time`always	number	In Unix milliseconds
`transfers[].asset`	string
`transfers[].amount`always	number
`transfers[].type`always	deposit \| withdraw \| transfer \| vaultDeposit \| vaultWithdraw \| commission \| other	deposit and withdraw move the owner's money into or out of the account; transfer, to or from another address; vaultDeposit and vaultWithdraw, into or out of a vault; commission is a vault leader's share; other is a kind none of these fits, named in sourceDetails.type
`transfers[].sourceDetails.type`	only dYdX
`transfers[].counterparty`	string
`transfers[].txHash`	string
`nextCursor`	string	Send it back as cursor, with the same query, to read the next page; absent on the last page

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/dydx/transferHistory?traderId=dydx1000qkj0ns34zk9706plzq4vk07kmgvkdaruddj"

{
  "data": {
    "transfers": [
      {
        "time": 1751143257268,
        "amount": 58.541965,
        "asset": "USDC",
        "type": "deposit",
        "sourceDetails": {
          "type": "DEPOSIT"
        },
        "txHash": "897D548E649B748616EE1E622FAC1F51694550518CD682DA99573655C1017DD1"
      },
      {
        "time": 1751131233450,
        "amount": 877.278757,
        "asset": "USDC",
        "type": "deposit",
        "sourceDetails": {
          "type": "DEPOSIT"
        },
        "txHash": "5B0981B92651F19E758A8CB186C558F6DEE6A919FFE28F0F5F5D5303B11B1784"
      }
    ]
  }
}

Order history

GET /v5/dydx/orderHistory

Filled perpetual orders, newest first, built from the latest fills (up to 1000): average price, quantity and fees. The oldest order may be missing fills read past the limit. dYdX offers no way to page further back.

Query parameters

Name	Type	Description
`traderId`required	string	A dYdX address (dydx1...)
`rows`	intdefault 500	Latest fills to read1 to 1000

Response fields, in `data`

Field	Type	Description
`orders[]`always	array
`orders[].symbol`always	string
`orders[].side`always	string
`orders[].positionSide`	string	BOTH in one-way mode; LONG or SHORT in hedge mode
`orders[].price`	number
`orders[].quantity`	number
`orders[].quoteQuantity`	number
`orders[].createdAt`	number	When the order was placed, in Unix milliseconds
`orders[].updatedAt`always	number	Last change, in Unix milliseconds
`orders[].sourceDetails.fills`	only dYdX
`orders[].orderType`	string	For example MARKET or LIMIT
`orders[].orderId`	string
`orders[].tradingFee`	number	Fees paid, in sourceDetails.feeToken; negative is a rebate

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/dydx/orderHistory?traderId=dydx1000qkj0ns34zk9706plzq4vk07kmgvkdaruddj"

{
  "data": {
    "orders": [
      {
        "symbol": "APEUSD",
        "side": "SELL",
        "positionSide": "BOTH",
        "price": 0.607,
        "quantity": 82,
        "quoteQuantity": 49.774,
        "createdAt": 1751225227428,
        "updatedAt": 1751225227428,
        "orderId": "b5032e25-fa1a-5595-aee5-68f387c0ed58",
        "orderType": "LIMIT",
        "tradingFee": 0.024887,
        "sourceDetails": {
          "fills": 1
        }
      },
      {
        "symbol": "WIFUSD",
        "side": "SELL",
        "positionSide": "BOTH",
        "price": 0.811,
        "quantity": 1081,
        "quoteQuantity": 876.691,
        "createdAt": 1751131423874,
        "updatedAt": 1751131423874,
        "orderId": "1ff415d3-3015-50c5-87e1-4dc63b38211b",
        "orderType": "LIMIT",
        "tradingFee": 0.08767,
        "sourceDetails": {
          "fills": 1
        }
      }
    ]
  }
}

Stream and webhooks

Paid plans can follow a trader in real time over wss://api.kopyon.com/v5/streamor through signed webhooks. Topics for this source:

openPositions: Open positions, whenever they change
positionEvents: Opened, increased, decreased, closed
orderHistory: New and updated orders
positionHistory: Newly closed positions

Stream messages and webhook signatures

dYdX API

Trader profile

Query parameters

Response fields, in data

Example

Trader chart

Query parameters

Response fields, in data

Example

Open positions

Query parameters

Response fields, in data

Example

Position history

Query parameters

Response fields, in data

Example

Transfer history

Query parameters

Response fields, in data

Example

Order history

Query parameters

Response fields, in data

Example

Stream and webhooks

Try the dYdX API for free.

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`