Below you can find API documentation for v1 of our positions REST API.
This API is reached via an HTTP GET and returns a JSON response.
The position information returned from our API is continuously synced with the positions on-chain.
Feel free to reach out with questions or comments to our shared slack group, or email me directly bryce@dydx.exchange with any further technical questions.
Production (MainNet)
Staging (Kovan)
This endpoint returns a JSON list of positions in the form:
{
"positions": [
{
"id": "0x5efff42fd6b97bf36930211044b1b83ef068867cf052174bf8baed0f228a3404",
"name": "Short Ethereum 11/01",
"type": "SHORT",
"principal": "1000000000000000000",
"collateral": "500000000000000000000",
"tokenSupply": null,
"closedHeldTokenRemaining": null,
"maxTokenSupply": null,
"marginCallStartAt": null,
"positionClosedAt": null,
"state": "ACTIVE",
"isMarginCalled": false,
"isClosing": false,
"closedReason": null,
"positionCreatedAt": null,
"positionExpiresAt": null,
"ownerAddress": "0x6a08b12aa520d319768e0d3a779af8660794c5e1",
"lenderAddress": "0x6a08b12aa520d319768e0d3a779af8660794c5e1",
"interestRate": 0.01,
"interestPeriodSeconds": 10,
"callTimeSeconds": 100,
"maxDurationSeconds": 100,
"tokenUuid": "51a2f4fc-b4a8-44e4-b4ff-b804e6b91e84",
"baseTokenUuid": "083ea8f5-769b-4d45-b11a-8290f50fbda2",
"quoteTokenUuid": "083ea8f5-769b-4d45-b11a-8290f50fbda3",
"createdAt": "2018-09-06T00:35:30.398Z",
"updatedAt": "2018-09-06T00:35:30.398Z",
"deletedAt": null,
"token": {
"uuid": "51a2f4fc-b4a8-44e4-b4ff-b804e6b91e84",
"symbol": "sETH 11/01",
"contractAddress": "0x4ae25380309718a506e50310c6f6643eefa7343f",
"decimals": 18,
"createdAt": "2018-09-04T22:35:40.878Z",
"updatedAt": "2018-09-04T22:35:40.878Z"
},
"baseToken": {
"uuid": "083ea8f5-769b-4d45-b11a-8290f50fbda2",
"symbol": "WETH",
"contractAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"decimals": 18,
"createdAt": "2018-09-06T00:34:57.237Z",
"updatedAt": "2018-09-06T00:34:57.237Z"
},
"quoteToken": {
"uuid": "083ea8f5-769b-4d45-b11a-8290f50fbda3",
"symbol": "DAI",
"contractAddress": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
"decimals": 18,
"createdAt": "2018-09-06T00:34:57.237Z",
"updatedAt": "2018-09-06T00:34:57.237Z"
}
}
]
}We consider positions to be in one of three high-level states. INACTIVE, ACTIVE, or CLOSED.
If INACTIVE, the position has been created in our systems internally, and we may have deployed the lending contract to start gathering lending liquidity, but the position has not yet been created on-chain, and tokens can not be minted or closed.
If ACTIVE, the position exists on-chain and tokens can be closed. Tokens may be minted so long as the position has not been margin-called and is not closing.
If CLOSED, the position has been closed and new tokens can not be minted, but existing tokens may be closed.
Certain fields may be null depending on the current state. For example, when a position is CLOSED it no longer has principal or collateral, so these values will always be null.
As you can see above, each position consists of a number of fields which can vary based on the state of the position.
Below is a description of each individual field in a position. All token amounts are denoted in base units.
| field name | description |
|---|---|
| id | Unique position identifier. The same ID used on-chain. |
| name | A human-readable name for the position. |
| type | The type of tokenized position. Currently only SHORT or LONG. |
| principal | The principal amount denoted in held token or null if the position is in a CLOSED state. E.g. for Short Ethereum, this would be denoted in ETH. |
| collateral | The collateral amount held in the position denoted in owed token or null if the position is in a CLOSED state. E.g. for Short Ethereum this would be denoted in DAI. |
| tokenSupply | When the position is in a CLOSED state, this field denotes the amount of remaining unclosed margin tokens. |
| closedHeldTokenRemaining | When the position is in a CLOSED state, this field denotes the amount of remaining held token locked in the position which may be withdrawn. |
| maxTokenSupply | A cap on the principal of the position. New tokens cannot be minted once the cap is reached. The cap may be raised during the lifetime of the position. |
| marginCallStartAt | An ISO-8601 date denoting the time at which a margin-call occured or null if a margin-call has not occurred. |
| positionClosedAt | An ISO-8601 date denoting the time at which the position was closed or null if the position has not been closed. |
| state | The current state of the position. Valid values are INACTIVE, ACTIVE, and CLOSED. |
| isMarginCalled | A boolean value denoting whether the position is in a margin-call state. |
| isClosing | A boolean value denoting whether the position is in a closing state. If in a closing state (either due to expiry, or being margin-called) the position is currently running the dutch auction closing mechanism and attempting to close the position at a fair price. |
| closedReason | If the position is in a CLOSED state, denotes the reason why the position was closed. Either MARGIN_CALL or EXPIRED. |
| positionCreatedAt | An ISO-8601 date denoting the time at which the position was created on-chain. |
| positionExpiresAt | An ISO-8601 date denoting the time at which the position will expire if not margin called. |
| ownerAddress | The Ethereum Address of the position contract owner. For tokenized positions, the address of the ERC20Position contract. |
| lenderAddress | The Ethereum Address of the position lender contract. For tokenized positions, the address of the BucketLender contract. |
| interestRate | The interest rate at which the borrower will pay the lender. Interest is defined as continuously compound interest over a period of 365 days where 1 is 100% interest. E.g. 0.01 would be 1% interest, continuously compounding, over a period of 365 days. |
| interestPeriodSeconds | The interest rate update period in seconds. Interest fee will increase once per period. |
| callTimeSeconds | The minimum amount of time (in seconds) that the position must be closed after being margin-called by the lender. |
| maxDurationSeconds | The maximum duration (in seconds) of the loan. Relative to when a position is opened. |
| tokenUuid | Internal identifier for the margin token. |
| baseTokenUuid | Internal identifier for the base token. |
| quoteTokenUuid | Internal identifier for the quote token. |
| createdAt | An ISO-8601 date denoting the time at which this record was created in our system. |
| updatedAt | An ISO-8601 date denoting the time at which this record was last updated in our system. |
| deletedAt | An ISO-8601 date denoting the time at which this record was deleted in our system. |
| token | A JSON object representing the short token including contract address, decimals, and symbol name. |
| baseToken | A JSON object representing the base token including contract address, decimals, and symbol name. |
| quoteToken | A JSON object representing the quote token including contract address, decimals, and symbol name. |