Welcome

Welcome to Paradex API

Here you'll find all the documentation you need to get up and running with the Paradex API.

API Server Location

Our API server is located in the AWS AP-NORTHEAST-1 region (Tokyo).
The best way to synchronize your clock with our servers is via the Amazon time service.

API URLs

Production


REST	`https://api.prod.paradex.trade/v1`
WebSocket	`wss://ws.api.prod.paradex.trade/v1`

Testnet


REST	`https://api.testnet.paradex.trade/v1`
WebSocket	`wss://ws.api.testnet.paradex.trade/v1`

Want to jump right in?

Feeling like an eager beaver? Jump in to the quick start docs to onboard yourself and send your first order.

Want to explore first?

Start with the REST API reference then jump to the WebSocket API to get real-time updates.

Quick start

Calling a public endpoint

import requests
headers = {'Accept': 'application/json'}
r = requests.get('https://api.testnet.paradex.trade/v1/markets', headers = headers)
print(r.json())

package main

import (
    "bytes"
    "net/http"
)

func main() {
    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/markets", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
}

curl -X GET https://api.testnet.paradex.trade/v1/markets \
  -H 'Accept: application/json'

const headers = {
  Accept: "application/json",
};
fetch("https://api.testnet.paradex.trade/v1/markets", {
  method: "GET",
  headers: headers,
})
  .then((res) => {
    return res.json();
  })
  .then((body) => {
    console.log(body);
  });

To dive right in you can start by trying a call to one of Paradex's public endpoints, GET /markets.

The response will look something like this:

{
  "results": [
    {
      "symbol": "ETH-USD-PERP",
      "base_currency": "ETH",
      "quote_currency": "USD",
      "settlement_currency": "USDC",
      "order_size_increment": "0.001",
      "price_tick_size": "0.01",
      "open_at":0,
      "expiry_at":0,
      "asset_kind": "PERP",
    }
  ]
}

Interacting with private endpoints

To interact with private Paradex endpoints you need to onboard and generate a JSON Web Token (JWT) before making API requests. JWTs are a secure way to transmit information between parties. Please refer to the Authentication chapter and onboarding and authentication code samples.

Authentication

Your software will have to authenticate itself when:

You onboard your wallet using automatic onboarding code
You generate JWT (see below) for a private Rest API call or subscription to a private WebSocket
You send order to Paradex

What is JWT

Paradex uses JSON Web Tokens (JWTs) to authenticate users.

JWTs are a secure way to transmit information between parties as they are signed by the sender, which allows the recipient to verify the authenticity of the message.

For security reasons JWTs used in Paradex's authentication mechanism expire every 5 minutes.

This means that users will need to re-authenticate regularly in order to always have a fresh JWT readily available.

Paradex recommends refreshing JWT well before expiry (e.g., after 3 minutes) to allow multiple retry attempts while still having a valid JWT.

This will help you to avoid interruptions in making REST API calls.

When using WebSocket connections, after the initial authentication, users do not need to re-authenticate again for the lifetime of the connection.

See more regarding Paradex JWT mechanism at https://docs.api.testnet.paradex.trade/#get-jwt.

Benefits of Using JWT

The benefits of using JWT for authentication:

Security: JWTs are signed by the issuer, which allows the recipient to verify the authenticity of the message.
Efficiency: JWTs are small and lightweight, which makes them efficient to transmit over the network.

Transaction Signing Benchmarks

Orders that you send to Paradex are signed to ensure that L2 StarkNet block-chain can verify the validity of your account.

Signing of orders functionality is implemented in several languages.

This section provides an overview of the speed of order signature in currently implemented programming languages.

Benchmarking Code

The benchmarking code (Go, Python) is available here

Rust implementation is here

C++ implementation is here

Benchmarking Results

Programming Language	Signatures per second	Signature latency in ms
Python	27	37
Python with C extension disabled	13	77
Go	590	1.695
Rust	5000	0.2
C++	2500	0.4

Rate Limits

1. API

1.1. Public Endpoints

The rate limit for all of our public API endpoints is set to a maximum of 10 requests per second per IP address.

Exceptions:

POST /onboarding & POST /auth: These endpoints have a shared rate limit of 1 request per second.

1.2. Private Endpoints (Per-account limits)

For our private API endpoints, the rate limit varies according to the specific endpoint:

POST /orders & DELETE /orders: These endpoints have a shared rate limit of 100 requests per second.
GET /*: All GET endpoints have a shared rate limit of 10 requests per second.

2. Websocket

2.1. Public Concurrent Connections

For public concurrent connections via our Websocket, the rate limit is set to a maximum of 10 connections per IP address.

2.2. Private Concurrent Connections

For private concurrent connections via our Websocket, the rate limit is set to a maximum of 100 connections per account.

3. Open Orders Per Account

The rate limit for open orders per account is set to a maximum of 100 orders per market.

4. Position Limit

Please refer to Position Limit section

5. Common Questions

Please refer to FAQ Rate Limits section.

Paradex REST API v1.69.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

The following describe Paradex API. Bear in mind that this is still a work in progress so all feedback is welcome.

Account

Get account information

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/account', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/account", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/account \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/account',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /account

Respond with requester's account information

Example responses

200 Response

{
  "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
  "account_value": "136285.06918911",
  "free_collateral": "73276.47229774",
  "initial_margin_requirement": "63008.59689218",
  "maintenance_margin_requirement": "31597.25239676",
  "margin_cushion": "104687.8167956",
  "seq_no": 1681471234972000000,
  "settlement_asset": "USDC",
  "status": "ACTIVE",
  "total_collateral": "123003.62047353",
  "updated_at": 1681471234972
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.AccountSummaryResponse
400	Bad Request	Bad Request	responses.ApiError
401	Unauthorized	Unauthorized	responses.ApiError

Get account profile information

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/account/profile', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/account/profile", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/account/profile \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/account/profile',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /account/profile

Respond with requester's account information

Example responses

200 Response

{
  "is_username_private": true,
  "username": "username"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.AccountProfileResp
400	Bad Request	Bad Request	responses.ApiError
401	Unauthorized	Unauthorized	responses.ApiError

Updates account profile fields

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.post('https://api.testnet.paradex.trade/v1/account/profile', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.testnet.paradex.trade/v1/account/profile", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X POST https://api.testnet.paradex.trade/v1/account/profile \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/account/profile',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /account/profile

Respond with requester's account information

Example responses

200 Response

{
  "is_username_private": true,
  "username": "username"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.AccountProfileResp
400	Bad Request	Bad Request	responses.ApiError
401	Unauthorized	Unauthorized	responses.ApiError

List balances

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/balance', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/balance", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/balance \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/balance',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /balance

Respond with requester's own balances

Example responses

200 Response

{
  "results": [
    {
      "last_updated_at": 1681462770114,
      "size": "123003.620",
      "token": "USDC"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.GetBalancesResp
400	Bad Request	Bad Request	responses.ApiError
401	Unauthorized	Unauthorized	responses.ApiError

List fills

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/fills', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/fills", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/fills \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/fills',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /fills

This API returns a list of matched orders (i.e. fills) that have been sent to chain for settlement.

Parameters

Name	In	Type	Required	Description
cursor	query	string	false	Returns the ‘next’ paginated page.
market	query	string	false	none
page_size	query	integer	false	Limit the number of responses in the page

Example responses

200 Response

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "client_id": "x1234",
      "created_at": 1681375176910,
      "fee": "7.56",
      "fee_currency": "USDC",
      "id": "8615262148007718462",
      "liquidity": "TAKER",
      "market": "BTC-USD-PERP",
      "order_id": "1681462103821101699438490000",
      "price": "30000.12",
      "remaining_size": "0.5",
      "side": "BUY",
      "size": "0.5"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.GetFillsResp
400	Bad Request	Bad Request	responses.ApiError
401	Unauthorized	Unauthorized	responses.ApiError

Funding payments history

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/funding/payments', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/funding/payments", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/funding/payments \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/funding/payments',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /funding/payments

List funding payments made by/to the requester's account

Funding payments are periodic payments between traders to make the perpetual futures contract price is close to the index price.

Parameters

Name	In	Type	Required	Description
cursor	query	string	false	Returns the ‘next’ paginated page.
market	query	string	false	Market for which funding payments are queried
page_size	query	integer	false	Limit the number of responses in the page

Example responses

200 Response

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "created_at": 1681375481000,
      "fill_id": "8615262148007718462",
      "id": "1681375578221101699352320000",
      "index": "-2819.53434361",
      "market": "BTC-USD-PERP",
      "payment": "34.4490622"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.FundingHistoryResp
400	Bad Request	Bad Request	responses.ApiError
401	Unauthorized	Unauthorized	responses.ApiError

List open positions

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/positions', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/positions", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/positions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/positions',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /positions

Get all positions owned by current user

Example responses

200 Response

{
  "results": [
    {
      "average_entry_price": "29001.34",
      "average_entry_price_usd": "29001.34",
      "cached_funding_index": "1234.3",
      "cost": "-10005.4623",
      "cost_usd": "-10005.4623",
      "id": "1234234",
      "last_fill_id": "1234234",
      "last_updated_at": 1681493939981,
      "market": "BTC-USD-PERP",
      "realized_pnl": "1234.3",
      "seq_no": 1681471234972000000,
      "side": "SHORT",
      "size": "-0.345",
      "status": "OPEN",
      "unrealized_funding_pnl": "12.234",
      "unrealized_pnl": "-123.23"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.GetPositionsResp

List tradebusts

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/tradebusts', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/tradebusts", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/tradebusts \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/tradebusts',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /tradebusts

Retrieves a list of tradebusts associated to the requester's account

Parameters

Name	In	Type	Required	Description
cursor	query	string	false	Returns the ‘next’ paginated page.
page_size	query	integer	false	Limit the number of responses in the page

Example responses

200 Response

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
      "busted_fill_id": "12342345",
      "created_at": 1681497002041
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.GetTradebustsResp
400	Bad Request	Bad Request	responses.ApiError

List transactions

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/transactions', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/transactions", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/transactions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/transactions',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /transactions

Retrieves a list of transactions initiated by the user

Parameters

Name	In	Type	Required	Description
cursor	query	string	false	Returns the ‘next’ paginated page.
page_size	query	integer	false	Limit the number of responses in the page

Example responses

200 Response

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "completed_at": 0,
      "created_at": 0,
      "hash": "0x445c05d6bfb899e39338440d199971c4d7f4cde7878ed3888df3f716efb8df2",
      "id": "12342423",
      "state": "ACCEPTED_ON_L1",
      "type": "TRANSACTION_LIQUIDATE"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.GetTransactionResponse
400	Bad Request	Bad Request	responses.ApiError

Authentication

Get JWT

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'PARADEX-STARKNET-ACCOUNT': 'string',
  'PARADEX-STARKNET-SIGNATURE': 'string',
  'PARADEX-TIMESTAMP': 'string',
  'PARADEX-SIGNATURE-EXPIRATION': 'string'
}

r = requests.post('https://api.testnet.paradex.trade/v1/auth', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "PARADEX-STARKNET-ACCOUNT": []string{"string"},
        "PARADEX-STARKNET-SIGNATURE": []string{"string"},
        "PARADEX-TIMESTAMP": []string{"string"},
        "PARADEX-SIGNATURE-EXPIRATION": []string{"string"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.testnet.paradex.trade/v1/auth", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X POST https://api.testnet.paradex.trade/v1/auth \
  -H 'Accept: application/json' \
  -H 'PARADEX-STARKNET-ACCOUNT: string' \
  -H 'PARADEX-STARKNET-SIGNATURE: string' \
  -H 'PARADEX-TIMESTAMP: string' \
  -H 'PARADEX-SIGNATURE-EXPIRATION: string'


const headers = {
  'Accept':'application/json',
  'PARADEX-STARKNET-ACCOUNT':'string',
  'PARADEX-STARKNET-SIGNATURE':'string',
  'PARADEX-TIMESTAMP':'string',
  'PARADEX-SIGNATURE-EXPIRATION':'string'
};

fetch('https://api.testnet.paradex.trade/v1/auth',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /auth

Authenticate using signed payload to get a JWT for usage in other endpoints

There are multiple valid headers required to be sent as part of this request.

For a complete onboarding example, refer to go or python code in code-samples.

StarkNet Message Hash and Signature

Inspired by EIP-712, (a standard for hashing and signing typed structured data) the encoding of an off-chain message is defined as:

signed_data = Enc[PREFIX_MESSAGE, domain_separator, account, hash_struct(message)]

where:

PREFIX_MESSAGE = "StarkNet Message"
domain_separator is defined as the hash_struct of the StarkNetDomain struct:
- Struct contains: name, chainId and version
- chainId is can be obtained calling GET /system/config
account is the StarkNet account address
The message to be hashed is represented as a struct
- hash_struct(message) = Enc[type_hash(MyStruct), Enc[param1], ..., Enc[paramN]]
- where type_hash is defined as in EIP-712 (but using selector instead of keccak)
- More details on StarkNet - Hash Functions

In case of more complex structure of object, you have to work in the spirit of EIP-712. This json structure has 4 mandatory items: types, primaryType, domain and message. These items are designed to be able to be an interface with a wallet. At sign request, the wallet will display:

message will be displayed at the bottom of the wallet display, showing clearly (not in hex) the message to sign. Its structure has to be in accordance with the type listed in primaryType, defined in types.
domain will be shown above the message. Its structure has to be in accordance with StarkNetDomain.

The predefined types that you can use :

felt : for an integer on 251 bits.
felt* : for an array of felt.
string : for a shortString of 31 ASCII characters max.
selector : for a name of a smart contract function.
merkletree : for a Root of a Merkle tree, calculated with the provided data.

Specification details: Signing transactions and off-chain messages

Message Hash Sample Code

For a complete message_hash example, refer to python code in code-samples.

Examples:

{
  "paradex-signature-expiration": 1682364556,
  "paradex-starknet-account": "0x129f3dc1b8962d8a87abc692424c78fda963ade0e1cd17bf3d1c26f8d41ee7a",
  "paradex-starknet-signature": [
    "1381323390094460587764867648394252677239485992175346764030313478865763678671",
    "396490140510115262427678549757564216013606350105112805717359873954984880589"
  ],
  "paradex-timestamp": 1681759756
}

Parameters

Name	In	Type	Required	Description
PARADEX-STARKNET-ACCOUNT	header	string	true	Starknet account
PARADEX-STARKNET-SIGNATURE	header	string	true	Starknet signature
PARADEX-TIMESTAMP	header	string	true	Timestamp when the signature was created
PARADEX-SIGNATURE-EXPIRATION	header	string	false	Timestamp when signature expires (default 30 min

Example responses

200 Response

{
  "jwt_token": "eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9.eyJ0eXAiOiJhdCtKV1QiLCJleHAiOjE2ODE0NTI5MDcsImlhdCI6MTY4MTQ1MjYwNywiaXNzIjoiUGFyYWRleCBzdGFnaW5nIiwic3ViIjoiMHg0OTVkMmViNTIzNmExMmI4YjRhZDdkMzg0OWNlNmEyMDNjZTIxYzQzZjQ3M2MyNDhkZmQ1Y2U3MGQ5NDU0ZmEifQ.BPihIbGhnnsuPlReqC9x12JFXldpswg5EdA6tTiDQm-_UHaRz_8RfVBqWc2fPN6CzFsXTq7GowZu-2qMxPvZK_fGcxEhTp2k1r8MUxowlUIT4vPu2scCwrsyIujlCAwS"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.AuthResp
400	Bad Request	Bad Request	responses.ApiError
401	Unauthorized	Unauthorized	responses.ApiError

Onboarding

Code samples

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'PARADEX-ETHEREUM-ACCOUNT': 'string',
  'PARADEX-STARKNET-ACCOUNT': 'string',
  'PARADEX-STARKNET-SIGNATURE': 'string'
}

r = requests.post('https://api.testnet.paradex.trade/v1/onboarding', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "PARADEX-ETHEREUM-ACCOUNT": []string{"string"},
        "PARADEX-STARKNET-ACCOUNT": []string{"string"},
        "PARADEX-STARKNET-SIGNATURE": []string{"string"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.testnet.paradex.trade/v1/onboarding", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X POST https://api.testnet.paradex.trade/v1/onboarding \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'PARADEX-ETHEREUM-ACCOUNT: string' \
  -H 'PARADEX-STARKNET-ACCOUNT: string' \
  -H 'PARADEX-STARKNET-SIGNATURE: string'

const inputBody = '{
  "public_key": "0x3d9f2b2e5f50c1aade60ca540368cd7490160f41270c192c05729fe35b656a9"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'PARADEX-ETHEREUM-ACCOUNT':'string',
  'PARADEX-STARKNET-ACCOUNT':'string',
  'PARADEX-STARKNET-SIGNATURE':'string'
};

fetch('https://api.testnet.paradex.trade/v1/onboarding',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /onboarding

Onboarding verifies that the caller owns the StarkNet address and enters them into the database. This call is idempotent.

Body parameter

{
  "public_key": "0x3d9f2b2e5f50c1aade60ca540368cd7490160f41270c192c05729fe35b656a9"
}

Parameters

Name	In	Type	Required	Description
PARADEX-ETHEREUM-ACCOUNT	header	string	true	Ethereum account used to onboard
PARADEX-STARKNET-ACCOUNT	header	string	true	Starknet address
PARADEX-STARKNET-SIGNATURE	header	string	true	Starknet signature
body	body	requests.Onboarding	true	Onboarding user public_key

Example responses

400 Response

{
  "data": null,
  "error": "NOT_ONBOARDED",
  "message": "User has never called /onboarding endpoint"
}

Responses

Status	Meaning	Description	Schema
200	OK	An empty response	None
400	Bad Request	Bad Request	responses.ApiError
401	Unauthorized	Unauthorized	responses.ApiError

Insurance

Get insurance fund account information

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.testnet.paradex.trade/v1/insurance', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/insurance", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/insurance \
  -H 'Accept: application/json'


const headers = {
  'Accept':'application/json'
};

fetch('https://api.testnet.paradex.trade/v1/insurance',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /insurance

Get insurance fund account's information

Example responses

200 Response

{
  "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
  "account_value": "136285.069",
  "settlement_asset": "USDC",
  "updated_at": 1681471234972
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.InsuranceAccountResp

Liquidations

List liquidations

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/liquidations', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/liquidations", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/liquidations \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/liquidations',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /liquidations

Retrieves a list of liquidations associated to the requester's account

Parameters

Name	In	Type	Required	Description
from	query	integer	false	Start Time (unix time millisecond)
to	query	integer	false	End Time (unix time millisecond)

Example responses

200 Response

{
  "results": [
    {
      "created_at": 1697213130097,
      "id": "0x123456789"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.GetLiquidations
400	Bad Request	Bad Request	responses.ApiError

Markets

List available markets

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.testnet.paradex.trade/v1/markets', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/markets", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/markets \
  -H 'Accept: application/json'


const headers = {
  'Accept':'application/json'
};

fetch('https://api.testnet.paradex.trade/v1/markets',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /markets

Get markets static data component

Parameters

Name	In	Type	Required	Description
market	query	string	false	Market Name - example: BTC-USD-PERP

Example responses

200 Response

{
  "results": [
    {
      "asset_kind": "PERP",
      "base_currency": "ETH",
      "expiry_at": 0,
      "max_funding_rate": "0.05",
      "max_open_orders": 100,
      "open_at": 0,
      "order_size_increment": "0.001",
      "position_limit": "500",
      "price_bands_width": "0.05",
      "price_tick_size": "0.01",
      "quote_currency": "USD",
      "settlement_currency": "USDC",
      "symbol": "ETH-USD-PERP"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.GetMarkets
404	Not Found	Not Found	responses.ApiError

List available markets summary

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.testnet.paradex.trade/v1/markets/summary', params={
  'market': 'BTC-USD-PERP'
}, headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/markets/summary", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/markets/summary?market=BTC-USD-PERP \
  -H 'Accept: application/json'


const headers = {
  'Accept':'application/json'
};

fetch('https://api.testnet.paradex.trade/v1/markets/summary?market=BTC-USD-PERP',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /markets/summary

Get markets dynamic data component

Parameters

Name	In	Type	Required	Description
end	query	integer	false	End Time (unix time millisecond)
market	query	string	true	Name of the market for which summary is requested (for all available markets use ALL)
start	query	integer	false	Start Time (unix time millisecond)

Example responses

200 Response

{
  "results": [
    {
      "ask": "30130.15",
      "bid": "30112.22",
      "created_at": 0,
      "funding_rate": "0.3",
      "last_traded_price": "30109.53",
      "open_interest": "6100048.3",
      "oracle_price": "29799.70877478",
      "symbol": "BTC-USD-PERP",
      "total_volume": "141341.0424",
      "underlying_price": "29876.3",
      "volume_24h": "47041.0424"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.GetMarketSummary
400	Bad Request	Bad Request	responses.ApiError

Get market orderbook

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.testnet.paradex.trade/v1/orderbook/{market}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/orderbook/{market}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/orderbook/{market} \
  -H 'Accept: application/json'


const headers = {
  'Accept':'application/json'
};

fetch('https://api.testnet.paradex.trade/v1/orderbook/{market}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /orderbook/{market}

Get snapshot of the orderbook for the given market

Parameters

Name	In	Type	Required	Description
market	path	string	true	Market symbol - ex: BTC-USD-PERP
depth	query	integer	false	Depth

Example responses

200 Response

{
  "asks": [
    [
      "string"
    ]
  ],
  "bids": [
    [
      "string"
    ]
  ],
  "last_updated_at": 1681462770114,
  "market": "ETH-USD-PERP",
  "seq_no": 20784
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.AskBidArray
400	Bad Request	Bad Request	responses.ApiError

Orders

Get open orders

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/orders', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/orders", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/orders \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/orders',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /orders

Get current user all open orders

Parameters

Name	In	Type	Required	Description
market	query	string	false	Market symbol, ex: BTC-USD-PERP

Example responses

200 Response

{
  "results": [
    {
      "account": "0x4638e3041366aa71720be63e32e53e1223316c7f0d56f7aa617542ed1e7512x",
      "avg_fill_price": "26000",
      "cancel_reason": "NOT_ENOUGH_MARGIN",
      "client_id": "x1234",
      "created_at": 1681493746016,
      "id": "123456",
      "instruction": "GTC",
      "last_updated_at": 1681493746016,
      "market": "BTC-USD-PERP",
      "price": "26000",
      "remaining_size": "0",
      "seq_no": 1681471234972000000,
      "side": "BUY",
      "size": "0.05",
      "status": "NEW",
      "stp": "EXPIRE_MAKER",
      "timestamp": 1681493746016,
      "type": "MARKET"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.GetOpenOrders
400	Bad Request	Bad Request	responses.ApiError

Create order

Code samples

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.post('https://api.testnet.paradex.trade/v1/orders', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.testnet.paradex.trade/v1/orders", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X POST https://api.testnet.paradex.trade/v1/orders \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'

const inputBody = '{
  "client_id": "123454321",
  "instruction": "string",
  "market": "BTC-USD-PERP",
  "price": "29500.12",
  "recv_window": 0,
  "side": "BUY",
  "signature": "string",
  "signature_timestamp": 0,
  "size": "1.213",
  "stp": "string",
  "type": "MARKET"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/orders',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /orders

Open a new order

Body parameter

{
  "client_id": "123454321",
  "instruction": "string",
  "market": "BTC-USD-PERP",
  "price": "29500.12",
  "recv_window": 0,
  "side": "BUY",
  "signature": "string",
  "signature_timestamp": 0,
  "size": "1.213",
  "stp": "string",
  "type": "MARKET"
}

Parameters

Name	In	Type	Required	Description
body	body	requests.OrderRequest	true	Order content

Example responses

201 Response

{
  "account": "0x4638e3041366aa71720be63e32e53e1223316c7f0d56f7aa617542ed1e7512x",
  "avg_fill_price": "26000",
  "cancel_reason": "NOT_ENOUGH_MARGIN",
  "client_id": "x1234",
  "created_at": 1681493746016,
  "id": "123456",
  "instruction": "GTC",
  "last_updated_at": 1681493746016,
  "market": "BTC-USD-PERP",
  "price": "26000",
  "remaining_size": "0",
  "seq_no": 1681471234972000000,
  "side": "BUY",
  "size": "0.05",
  "status": "NEW",
  "stp": "EXPIRE_MAKER",
  "timestamp": 1681493746016,
  "type": "MARKET"
}

Responses

Status	Meaning	Description	Schema
201	Created	Created	responses.OrderResp
400	Bad Request	Bad Request	responses.ApiError

Cancel all open orders

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.delete('https://api.testnet.paradex.trade/v1/orders', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.testnet.paradex.trade/v1/orders", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X DELETE https://api.testnet.paradex.trade/v1/orders \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/orders',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /orders

Parameters

Name	In	Type	Required	Description
market	query	string	false	Market to cancel orders for

Example responses

400 Response

{
  "data": null,
  "error": "NOT_ONBOARDED",
  "message": "User has never called /onboarding endpoint"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	None
400	Bad Request	Bad Request	responses.ApiError

Get orders

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/orders-history', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/orders-history", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/orders-history \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/orders-history',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /orders-history

Get current user orders filtered on attributes

Parameters

Name	In	Type	Required	Description
client_id	query	string	false	Unique ID of client generating the order
cursor	query	string	false	Returns the ‘next’ paginated page.
market	query	string	false	Market for the order
page_size	query	integer	false	Limit the number of responses in the page
side	query	string	false	Order side
status	query	string	false	Order status
type	query	string	false	Order type

Enumerated Values

Parameter	Value
side	BUY
side	SELL
status	OPEN
status	CLOSED
status	NEW
type	LIMIT
type	MARKET

Example responses

200 Response

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "account": "0x4638e3041366aa71720be63e32e53e1223316c7f0d56f7aa617542ed1e7512x",
      "avg_fill_price": "26000",
      "cancel_reason": "NOT_ENOUGH_MARGIN",
      "client_id": "x1234",
      "created_at": 1681493746016,
      "id": "123456",
      "instruction": "GTC",
      "last_updated_at": 1681493746016,
      "market": "BTC-USD-PERP",
      "price": "26000",
      "remaining_size": "0",
      "seq_no": 1681471234972000000,
      "side": "BUY",
      "size": "0.05",
      "status": "NEW",
      "stp": "EXPIRE_MAKER",
      "timestamp": 1681493746016,
      "type": "MARKET"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.GetOrders
400	Bad Request	Bad Request	responses.ApiError

Get order status by client order id

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/orders/by_client_id/{client_id}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/orders/by_client_id/{client_id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/orders/by_client_id/{client_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/orders/by_client_id/{client_id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /orders/by_client_id/{client_id}

Parameters

Name	In	Type	Required	Description
client_id	path	string	true	Client Order Id

Example responses

200 Response

{
  "account": "0x4638e3041366aa71720be63e32e53e1223316c7f0d56f7aa617542ed1e7512x",
  "avg_fill_price": "26000",
  "cancel_reason": "NOT_ENOUGH_MARGIN",
  "client_id": "x1234",
  "created_at": 1681493746016,
  "id": "123456",
  "instruction": "GTC",
  "last_updated_at": 1681493746016,
  "market": "BTC-USD-PERP",
  "price": "26000",
  "remaining_size": "0",
  "seq_no": 1681471234972000000,
  "side": "BUY",
  "size": "0.05",
  "status": "NEW",
  "stp": "EXPIRE_MAKER",
  "timestamp": 1681493746016,
  "type": "MARKET"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.OrderResp
400	Bad Request	Bad Request	responses.ApiError

Cancel open order by client order id

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.delete('https://api.testnet.paradex.trade/v1/orders/by_client_id/{client_id}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.testnet.paradex.trade/v1/orders/by_client_id/{client_id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X DELETE https://api.testnet.paradex.trade/v1/orders/by_client_id/{client_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/orders/by_client_id/{client_id}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /orders/by_client_id/{client_id}

Parameters

Name	In	Type	Required	Description
client_id	path	string	true	Client Order Id

Example responses

400 Response

{
  "data": null,
  "error": "NOT_ONBOARDED",
  "message": "User has never called /onboarding endpoint"
}

Responses

Status	Meaning	Description	Schema
204	No Content	No Content	None
400	Bad Request	Bad Request	responses.ApiError

Get order

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/orders/{order_id}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/orders/{order_id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/orders/{order_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/orders/{order_id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /orders/{order_id}

Parameters

Name	In	Type	Required	Description
order_id	path	string	true	Order Id

Example responses

200 Response

{
  "account": "0x4638e3041366aa71720be63e32e53e1223316c7f0d56f7aa617542ed1e7512x",
  "avg_fill_price": "26000",
  "cancel_reason": "NOT_ENOUGH_MARGIN",
  "client_id": "x1234",
  "created_at": 1681493746016,
  "id": "123456",
  "instruction": "GTC",
  "last_updated_at": 1681493746016,
  "market": "BTC-USD-PERP",
  "price": "26000",
  "remaining_size": "0",
  "seq_no": 1681471234972000000,
  "side": "BUY",
  "size": "0.05",
  "status": "NEW",
  "stp": "EXPIRE_MAKER",
  "timestamp": 1681493746016,
  "type": "MARKET"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.OrderResp
400	Bad Request	Bad Request	responses.ApiError

Cancel order

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.delete('https://api.testnet.paradex.trade/v1/orders/{order_id}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.testnet.paradex.trade/v1/orders/{order_id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X DELETE https://api.testnet.paradex.trade/v1/orders/{order_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/orders/{order_id}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /orders/{order_id}

Parameters

Name	In	Type	Required	Description
order_id	path	string	true	Order Id

Example responses

400 Response

{
  "data": null,
  "error": "NOT_ONBOARDED",
  "message": "User has never called /onboarding endpoint"
}

Responses

Status	Meaning	Description	Schema
204	No Content	No Content	None
400	Bad Request	Bad Request	responses.ApiError

System

Get system config

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.testnet.paradex.trade/v1/system/config', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/system/config", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/system/config \
  -H 'Accept: application/json'


const headers = {
  'Accept':'application/json'
};

fetch('https://api.testnet.paradex.trade/v1/system/config',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /system/config

Get clearing and settlement layer config for Paradex

Example responses

200 Response

{
  "block_explorer_url": "https://voyager.testnet.paradex.trade/",
  "bridged_tokens": [
    {
      "decimals": 0,
      "l1_bridge_address": "string",
      "l1_token_address": "string",
      "l2_bridge_address": "string",
      "l2_token_address": "string",
      "name": "string",
      "symbol": "string"
    }
  ],
  "l1_chain_id": "5",
  "l1_core_contract_address": "0x182FE62c57461d4c5Ab1aE6F04f1D51aA1607daf",
  "l1_operator_address": "0x63e762538C70442758Fd622116d817761c94FD6A",
  "liquidation_fee": "0.20",
  "oracle_address": "0x47c622ce5f7ff7fa17725df596f4f506364e49be0621eb142a75b44ee3689c6",
  "paraclear_account_hash": "0x033434ad846cdd5f23eb73ff09fe6fddd568284a0fb7d1be20ee482f044dabe2",
  "paraclear_account_proxy_hash": "0x3530cc4759d78042f1b543bf797f5f3d647cde0388c33734cf91b7f7b9314a9",
  "paraclear_address": "0x4638e3041366aa71720be63e32e53e1223316c7f0d56f7aa617542ed1e7554d",
  "paraclear_decimals": 0,
  "starknet_chain_id": "SN_CHAIN_ID",
  "starknet_gateway_url": "https://potc-testnet-02.starknet.io"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.SystemConfigResponse

Get system state

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.testnet.paradex.trade/v1/system/state', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/system/state", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/system/state \
  -H 'Accept: application/json'


const headers = {
  'Accept':'application/json'
};

fetch('https://api.testnet.paradex.trade/v1/system/state',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /system/state

Get the current state of the Paradex system

Example responses

200 Response

{
  "status": "ok"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.SystemStateResponse

Get system time (unix milliseconds)

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.testnet.paradex.trade/v1/system/time', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/system/time", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/system/time \
  -H 'Accept: application/json'


const headers = {
  'Accept':'application/json'
};

fetch('https://api.testnet.paradex.trade/v1/system/time',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /system/time

Get the current time in the Paradex

Example responses

200 Response

{
  "server_time": "1681493415023"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.SystemTimeResponse

Trades

Trade tape

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.testnet.paradex.trade/v1/trades', params={
  'market': 'BTC-USD-PERP'
}, headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/trades", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/trades?market=BTC-USD-PERP \
  -H 'Accept: application/json'


const headers = {
  'Accept':'application/json'
};

fetch('https://api.testnet.paradex.trade/v1/trades?market=BTC-USD-PERP',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /trades

List trades that happened on a given market (trade tape).

Parameters

Name	In	Type	Required	Description
cursor	query	string	false	Returns the ‘next’ paginated page.
market	query	string	true	Market name
page_size	query	integer	false	Limit the number of responses in the page

Example responses

200 Response

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "created_at": 1681497002041,
      "id": "12345643",
      "market": "BTC-USD-PERP",
      "price": "30001.2",
      "side": "BUY",
      "size": "0.01"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.GetTradesResp
400	Bad Request	Bad Request	responses.ApiError

Transfers

List account's transfers, i.e. deposits and withdrawals

Code samples

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {JWT}'
}

r = requests.get('https://api.testnet.paradex.trade/v1/transfers', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {JWT}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.testnet.paradex.trade/v1/transfers", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

# You can also use wget
curl -X GET https://api.testnet.paradex.trade/v1/transfers \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {JWT}'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {JWT}'
};

fetch('https://api.testnet.paradex.trade/v1/transfers',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /transfers

Parameters

Name	In	Type	Required	Description
cursor	query	string	false	Returns the ‘next’ paginated page.
page_size	query	integer	false	Limit the number of responses in the page
status	query	string	false	none

Enumerated Values

Parameter	Value
status	PENDING
status	AVAILABLE
status	COMPLETED
status	FAILED

Example responses

200 Response

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
      "amount": "100",
      "created_at": 1681497002041,
      "id": "123456789",
      "kind": "DEPOSIT",
      "last_updated_at": 1681497002041,
      "socialized_loss_factor": "0",
      "status": "PENDING",
      "token": "USDC",
      "txn_hash": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
      "txn_hash_l1": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	responses.GetTransfersResponse
400	Bad Request	Bad Request	responses.ApiError

Schemas

requests.Onboarding

{
  "public_key": "0x3d9f2b2e5f50c1aade60ca540368cd7490160f41270c192c05729fe35b656a9"
}

Properties

Name	Type	Required	Description
public_key	string	false	Public key of the user being onboarded.

requests.OrderRequest

{
  "client_id": "123454321",
  "instruction": "string",
  "market": "BTC-USD-PERP",
  "price": "29500.12",
  "recv_window": 0,
  "side": "BUY",
  "signature": "string",
  "signature_timestamp": 0,
  "size": "1.213",
  "stp": "string",
  "type": "MARKET"
}

Properties

Name	Type	Required	Description
client_id	string	false	Unique client assigned ID for the order
instruction	string	true	Order Instruction, GTC, IOC or POST_ONLY if empty GTC
market	string	true	Market for which order is createds
price	string	true	Order price
recv_window	integer	false	Order will be created if it is received by API within RecvWindow milliseconds from signature timestamp, minimum is 10 milliseconds
side	responses.OrderSide	true	Order side
signature	string	true	Order Payload signed with STARK Private Key
signature_timestamp	integer	true	Timestamp of order creation, used for signature verification
size	string	true	Size of the order
stp	string	false	Self Trade Prevention, EXPIRE_MAKER, EXPIRE_TAKER or EXPIRE_BOTH, if empty EXPIRE_TAKER
type	responses.OrderType	true	Order type

responses.AccountProfileResp

{
  "is_username_private": true,
  "username": "username"
}

Properties

Name	Type	Required	Description
is_username_private	boolean	false	none
username	string	false	none

responses.AccountSummaryResponse

{
  "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
  "account_value": "136285.06918911",
  "free_collateral": "73276.47229774",
  "initial_margin_requirement": "63008.59689218",
  "maintenance_margin_requirement": "31597.25239676",
  "margin_cushion": "104687.8167956",
  "seq_no": 1681471234972000000,
  "settlement_asset": "USDC",
  "status": "ACTIVE",
  "total_collateral": "123003.62047353",
  "updated_at": 1681471234972
}

Properties

Name	Type	Required	Description
account	string	false	User's starknet account
account_value	string	false	Current account value [with unrealized P&Ls]
free_collateral	string	false	Free collateral available (Account value in excess of Initial Margin required)
initial_margin_requirement	string	false	Amount required to open trade for the existing positions
maintenance_margin_requirement	string	false	Amount required to maintain exisiting positions
margin_cushion	string	false	Acc value in excess of maintenance margin required
seq_no	integer	false	Unique increasing number (non-sequential) that is assigned to this account update. Can be used to deduplicate multiple feeds
settlement_asset	string	false	Settlement asset for the account
status	string	false	Status of the acc - like ACTIVE, LIQUIDATION
total_collateral	string	false	User's total collateral
updated_at	integer	false	Account last updated time

responses.ApiError

{
  "data": null,
  "error": "NOT_ONBOARDED",
  "message": "User has never called /onboarding endpoint"
}

Properties

Name	Type	Required	Description
data	any	false	any additional data related to the error
error	responses.ErrorCode	false	unique immutable string identifier for specific error
message	string	false	detailed description of error and how to address it

responses.AskBidArray

{
  "asks": [
    [
      "string"
    ]
  ],
  "bids": [
    [
      "string"
    ]
  ],
  "last_updated_at": 1681462770114,
  "market": "ETH-USD-PERP",
  "seq_no": 20784
}

Properties

Name	Type	Required	Description
asks	[array]	false	List of Ask sizes and prices
bids	[array]	false	List of Bid sizes and prices
last_updated_at	integer	false	Last update to the orderbook in milliseconds
market	string	false	Market name
seq_no	integer	false	Sequence number of the orderbook

responses.AuthResp

{
  "jwt_token": "eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9.eyJ0eXAiOiJhdCtKV1QiLCJleHAiOjE2ODE0NTI5MDcsImlhdCI6MTY4MTQ1MjYwNywiaXNzIjoiUGFyYWRleCBzdGFnaW5nIiwic3ViIjoiMHg0OTVkMmViNTIzNmExMmI4YjRhZDdkMzg0OWNlNmEyMDNjZTIxYzQzZjQ3M2MyNDhkZmQ1Y2U3MGQ5NDU0ZmEifQ.BPihIbGhnnsuPlReqC9x12JFXldpswg5EdA6tTiDQm-_UHaRz_8RfVBqWc2fPN6CzFsXTq7GowZu-2qMxPvZK_fGcxEhTp2k1r8MUxowlUIT4vPu2scCwrsyIujlCAwS"
}

Properties

Name	Type	Required	Description
jwt_token	string	false	Authentication token

responses.BalanceResp

{
  "last_updated_at": 1681462770114,
  "size": "123003.620",
  "token": "USDC"
}

Properties

Name	Type	Required	Description
last_updated_at	integer	false	Balance last updated time
size	string	false	Balance amount
token	string	false	Name of the token

responses.BridgedToken

{
  "decimals": 0,
  "l1_bridge_address": "string",
  "l1_token_address": "string",
  "l2_bridge_address": "string",
  "l2_token_address": "string",
  "name": "string",
  "symbol": "string"
}

Properties

Name	Type	Required	Description
decimals	integer	false	none
l1_bridge_address	string	false	none
l1_token_address	string	false	none
l2_bridge_address	string	false	none
l2_token_address	string	false	none
name	string	false	none
symbol	string	false	none

responses.ErrorCode

"VALIDATION_ERROR"

Properties

Name	Type	Required	Description
anonymous	string	false	none

Enumerated Values

Property	Value
anonymous	VALIDATION_ERROR
anonymous	BINDING_ERROR
anonymous	INTERNAL_ERROR
anonymous	NOT_FOUND
anonymous	SERVICE_UNAVAILABLE
anonymous	INVALID_REQUEST_PARAMETER
anonymous	ORDER_ID_NOT_FOUND
anonymous	ORDER_IS_CLOSED
anonymous	ORDER_IS_NOT_OPEN_YET
anonymous	CLIENT_ORDER_ID_NOT_FOUND
anonymous	DUPLICATED_CLIENT_ID
anonymous	INVALID_PRICE_PRECISION
anonymous	INVALID_TOKEN
anonymous	INVALID_ETHEREUM_ADDRESS
anonymous	INVALID_ETHEREUM_SIGNATURE
anonymous	INVALID_STARKNET_ADDRESS
anonymous	INVALID_STARKNET_SIGNATURE
anonymous	STARKNET_SIGNATURE_VERIFICATION_FAILED
anonymous	BAD_STARKNET_REQUEST
anonymous	ETHEREUM_SIGNER_MISMATCH
anonymous	ETHEREUM_HASH_MISMATCH
anonymous	NOT_ONBOARDED
anonymous	INVALID_TIMESTAMP
anonymous	INVALID_SIGNATURE_EXPIRATION
anonymous	ACCOUNT_NOT_FOUND
anonymous	INVALID_ORDER_SIGNATURE
anonymous	PUBLIC_KEY_INVALID
anonymous	UNAUTHORIZED_ETHEREUM_ADDRESS
anonymous	ETHEREUM_ADDRESS_ALREADY_ONBOARDED
anonymous	MARKET_NOT_FOUND
anonymous	ALLOWLIST_ENTRY_NOT_FOUND
anonymous	USERNAME_IN_USE
anonymous	GEO_IP_BLOCK

responses.FillResult

{
  "client_id": "x1234",
  "created_at": 1681375176910,
  "fee": "7.56",
  "fee_currency": "USDC",
  "id": "8615262148007718462",
  "liquidity": "TAKER",
  "market": "BTC-USD-PERP",
  "order_id": "1681462103821101699438490000",
  "price": "30000.12",
  "remaining_size": "0.5",
  "side": "BUY",
  "size": "0.5"
}

Properties

Name	Type	Required	Description
client_id	string	false	Unique client assigned ID for the order
created_at	integer	false	Fill time
fee	string	false	Fee paid by the user
fee_currency	string	false	Asset that fee is charged in
id	string	false	Unique string ID of the fill
liquidity	responses.TraderRole	false	Maker or Taker
market	string	false	Market name
order_id	string	false	Order ID
price	string	false	Price at which order was filled
remaining_size	string	false	Remaining size of the order
side	responses.OrderSide	false	Taker side
size	string	false	Size of the fill

responses.FundingHistoryResp

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "created_at": 1681375481000,
      "fill_id": "8615262148007718462",
      "id": "1681375578221101699352320000",
      "index": "-2819.53434361",
      "market": "BTC-USD-PERP",
      "payment": "34.4490622"
    }
  ]
}

Properties

Name	Type	Required	Description
next	string	false	The pointer to fetch next set of records (null if there are no records left)
prev	string	false	The pointer to fetch previous set of records (null if there are no records left)
results	[responses.FundingResp]	false	Funding Response data list

responses.FundingResp

{
  "created_at": 1681375481000,
  "fill_id": "8615262148007718462",
  "id": "1681375578221101699352320000",
  "index": "-2819.53434361",
  "market": "BTC-USD-PERP",
  "payment": "34.4490622"
}

Properties

Name	Type	Required	Description
created_at	integer	false	Funding payments time
fill_id	string	false	Unique string ID for the fill that triggered the payment (if any)
id	string	false	Unique string ID to identify the payment
index	string	false	Value of the funding index at the time of payment
market	string	false	Perpetual market against which payment is made
payment	string	false	Payment amount in settlement asset

responses.GetBalancesResp

{
  "results": [
    {
      "last_updated_at": 1681462770114,
      "size": "123003.620",
      "token": "USDC"
    }
  ]
}

Properties

Name	Type	Required	Description
results	[responses.BalanceResp]	false	Array of token balances held

responses.GetFillsResp

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "client_id": "x1234",
      "created_at": 1681375176910,
      "fee": "7.56",
      "fee_currency": "USDC",
      "id": "8615262148007718462",
      "liquidity": "TAKER",
      "market": "BTC-USD-PERP",
      "order_id": "1681462103821101699438490000",
      "price": "30000.12",
      "remaining_size": "0.5",
      "side": "BUY",
      "size": "0.5"
    }
  ]
}

Properties

Name	Type	Required	Description
next	string	false	The pointer to fetch next set of records (null if there are no records left)
prev	string	false	The pointer to fetch previous set of records (null if there are no records left)
results	[responses.FillResult]	false	Fill Results List

responses.GetLiquidations

{
  "results": [
    {
      "created_at": 1697213130097,
      "id": "0x123456789"
    }
  ]
}

Properties

Name	Type	Required	Description
results	[responses.LiquidationResp]	false	List of liquidations

responses.GetMarketSummary

{
  "results": [
    {
      "ask": "30130.15",
      "bid": "30112.22",
      "created_at": 0,
      "funding_rate": "0.3",
      "last_traded_price": "30109.53",
      "open_interest": "6100048.3",
      "oracle_price": "29799.70877478",
      "symbol": "BTC-USD-PERP",
      "total_volume": "141341.0424",
      "underlying_price": "29876.3",
      "volume_24h": "47041.0424"
    }
  ]
}

Properties

Name	Type	Required	Description
results	[responses.MarketSummaryResp]	false	List of market summaries

responses.GetMarkets

{
  "results": [
    {
      "asset_kind": "PERP",
      "base_currency": "ETH",
      "expiry_at": 0,
      "max_funding_rate": "0.05",
      "max_open_orders": 100,
      "open_at": 0,
      "order_size_increment": "0.001",
      "position_limit": "500",
      "price_bands_width": "0.05",
      "price_tick_size": "0.01",
      "quote_currency": "USD",
      "settlement_currency": "USDC",
      "symbol": "ETH-USD-PERP"
    }
  ]
}

Properties

Name	Type	Required	Description
results	[responses.MarketResp]	false	List of available active markets

responses.GetOpenOrders

{
  "results": [
    {
      "account": "0x4638e3041366aa71720be63e32e53e1223316c7f0d56f7aa617542ed1e7512x",
      "avg_fill_price": "26000",
      "cancel_reason": "NOT_ENOUGH_MARGIN",
      "client_id": "x1234",
      "created_at": 1681493746016,
      "id": "123456",
      "instruction": "GTC",
      "last_updated_at": 1681493746016,
      "market": "BTC-USD-PERP",
      "price": "26000",
      "remaining_size": "0",
      "seq_no": 1681471234972000000,
      "side": "BUY",
      "size": "0.05",
      "status": "NEW",
      "stp": "EXPIRE_MAKER",
      "timestamp": 1681493746016,
      "type": "MARKET"
    }
  ]
}

Properties

Name	Type	Required	Description
results	[responses.OrderResp]	false	Orders list

responses.GetOrders

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "account": "0x4638e3041366aa71720be63e32e53e1223316c7f0d56f7aa617542ed1e7512x",
      "avg_fill_price": "26000",
      "cancel_reason": "NOT_ENOUGH_MARGIN",
      "client_id": "x1234",
      "created_at": 1681493746016,
      "id": "123456",
      "instruction": "GTC",
      "last_updated_at": 1681493746016,
      "market": "BTC-USD-PERP",
      "price": "26000",
      "remaining_size": "0",
      "seq_no": 1681471234972000000,
      "side": "BUY",
      "size": "0.05",
      "status": "NEW",
      "stp": "EXPIRE_MAKER",
      "timestamp": 1681493746016,
      "type": "MARKET"
    }
  ]
}

Properties

Name	Type	Required	Description
next	string	false	The pointer to fetch next set of records (null if there are no records left)
prev	string	false	The pointer to fetch previous set of records (null if there are no records left)
results	[responses.OrderResp]	false	List of Orders

responses.GetPositionsResp

{
  "results": [
    {
      "average_entry_price": "29001.34",
      "average_entry_price_usd": "29001.34",
      "cached_funding_index": "1234.3",
      "cost": "-10005.4623",
      "cost_usd": "-10005.4623",
      "id": "1234234",
      "last_fill_id": "1234234",
      "last_updated_at": 1681493939981,
      "market": "BTC-USD-PERP",
      "realized_pnl": "1234.3",
      "seq_no": 1681471234972000000,
      "side": "SHORT",
      "size": "-0.345",
      "status": "OPEN",
      "unrealized_funding_pnl": "12.234",
      "unrealized_pnl": "-123.23"
    }
  ]
}

Properties

Name	Type	Required	Description
results	[responses.PositionResp]	false	none

responses.GetTradebustsResp

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
      "busted_fill_id": "12342345",
      "created_at": 1681497002041
    }
  ]
}

Properties

Name	Type	Required	Description
next	string	false	The pointer to fetch next set of records (null if there are no records left)
prev	string	false	The pointer to fetch previous set of records (null if there are no records left)
results	[responses.TradebustResult]	false	List of tradebusts

responses.GetTradesResp

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "created_at": 1681497002041,
      "id": "12345643",
      "market": "BTC-USD-PERP",
      "price": "30001.2",
      "side": "BUY",
      "size": "0.01"
    }
  ]
}

Properties

Name	Type	Required	Description
next	string	false	The pointer to fetch next set of records (null if there are no records left)
prev	string	false	The pointer to fetch previous set of records (null if there are no records left)
results	[responses.TradeResult]	false	List of trade details

responses.GetTransactionResponse

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "completed_at": 0,
      "created_at": 0,
      "hash": "0x445c05d6bfb899e39338440d199971c4d7f4cde7878ed3888df3f716efb8df2",
      "id": "12342423",
      "state": "ACCEPTED_ON_L1",
      "type": "TRANSACTION_LIQUIDATE"
    }
  ]
}

Properties

Name	Type	Required	Description
next	string	false	The pointer to fetch next set of records (null if there are no records left)
prev	string	false	The pointer to fetch previous set of records (null if there are no records left)
results	[responses.TransactionResponse]	false	List of transaction responses

responses.GetTransfersResponse

{
  "next": "eyJmaWx0ZXIiMsIm1hcmtlciI6eyJtYXJrZXIiOiIxNjc1NjUwMDE3NDMxMTAxNjk5N=",
  "prev": "eyJmaWx0ZXIiOnsiTGltaXQiOjkwfSwidGltZSI6MTY4MTY3OTgzNzk3MTMwOTk1MywibWFya2VyIjp7Im1zMjExMD==",
  "results": [
    {
      "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
      "amount": "100",
      "created_at": 1681497002041,
      "id": "123456789",
      "kind": "DEPOSIT",
      "last_updated_at": 1681497002041,
      "socialized_loss_factor": "0",
      "status": "PENDING",
      "token": "USDC",
      "txn_hash": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
      "txn_hash_l1": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa"
    }
  ]
}

Properties

Name	Type	Required	Description
next	string	false	The pointer to fetch next set of records (null if there are no records left)
prev	string	false	The pointer to fetch previous set of records (null if there are no records left)
results	[responses.TransferResult]	false	List of transaction responses

responses.InsuranceAccountResp

{
  "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
  "account_value": "136285.069",
  "settlement_asset": "USDC",
  "updated_at": 1681471234972
}

Properties

Name	Type	Required	Description
account	string	false	Starknet address of the Insurance fund
account_value	string	false	Total account value of insurance fund
settlement_asset	string	false	Settlement Asset for the account
updated_at	integer	false	Account last updated time

responses.LiquidationResp

{
  "created_at": 1697213130097,
  "id": "0x123456789"
}

Properties

Name	Type	Required	Description
created_at	integer	false	Liquidation created at timestamp
id	string	false	Liquidation transaction hash

responses.MarketResp

{
  "asset_kind": "PERP",
  "base_currency": "ETH",
  "expiry_at": 0,
  "max_funding_rate": "0.05",
  "max_open_orders": 100,
  "open_at": 0,
  "order_size_increment": "0.001",
  "position_limit": "500",
  "price_bands_width": "0.05",
  "price_tick_size": "0.01",
  "quote_currency": "USD",
  "settlement_currency": "USDC",
  "symbol": "ETH-USD-PERP"
}

Properties

Name	Type	Required	Description
asset_kind	string	false	Type of asset
base_currency	string	false	Base currency of the market pair
expiry_at	integer	false	Market expiry time
max_funding_rate	string	false	Max funding rate
max_open_orders	integer	false	Max open orders
open_at	integer	false	Market open time in milliseconds
order_size_increment	string	false	Min tick size for base currency
position_limit	string	false	Position limit
price_bands_width	string	false	Price Bands Width, 0.05 means 5% price deviation allowed from mark price
price_tick_size	string	false	Min tick size for quote currency
quote_currency	string	false	Quote currency of the market pair
settlement_currency	string	false	Settlement currency of the market pair
symbol	string	false	Market symbol

responses.MarketSummaryResp

{
  "ask": "30130.15",
  "bid": "30112.22",
  "created_at": 0,
  "funding_rate": "0.3",
  "last_traded_price": "30109.53",
  "open_interest": "6100048.3",
  "oracle_price": "29799.70877478",
  "symbol": "BTC-USD-PERP",
  "total_volume": "141341.0424",
  "underlying_price": "29876.3",
  "volume_24h": "47041.0424"
}

Properties

Name	Type	Required	Description
ask	string	false	Last ask price
bid	string	false	Last bid price
created_at	integer	false	Market summary creation time
funding_rate	string	false	Funding rate 24hr
last_traded_price	string	false	Last traded price for the given market
open_interest	string	false	Open interest in base currency
oracle_price	string	false	Computed oracle price for the market
symbol	string	false	Symbol of the market pair
total_volume	string	false	Total all time volume for the market in USD
underlying_price	string	false	Underlying asset price
volume_24h	string	false	24 hour volume in USD

responses.OrderInstruction

"GTC"

Properties

Name	Type	Required	Description
anonymous	string	false	none

Enumerated Values

Property	Value
anonymous	GTC
anonymous	POST_ONLY
anonymous	IOC

responses.OrderResp

{
  "account": "0x4638e3041366aa71720be63e32e53e1223316c7f0d56f7aa617542ed1e7512x",
  "avg_fill_price": "26000",
  "cancel_reason": "NOT_ENOUGH_MARGIN",
  "client_id": "x1234",
  "created_at": 1681493746016,
  "id": "123456",
  "instruction": "GTC",
  "last_updated_at": 1681493746016,
  "market": "BTC-USD-PERP",
  "price": "26000",
  "remaining_size": "0",
  "seq_no": 1681471234972000000,
  "side": "BUY",
  "size": "0.05",
  "status": "NEW",
  "stp": "EXPIRE_MAKER",
  "timestamp": 1681493746016,
  "type": "MARKET"
}

Properties

Name	Type	Required	Description
account	string	false	Account identifier (user's account address)
avg_fill_price	string	false	Average fill price of the order
cancel_reason	string	false	Reason for order cancellation if it was closed by cancel
client_id	string	false	Client id passed on order creation
created_at	integer	false	Order creation time
id	string	false	Unique order identifier
instruction	responses.OrderInstruction	false	OrderInstruction (GTC, IOC, POST_ONLY)
last_updated_at	integer	false	Order last update time. No changes once status=CLOSED
market	string	false	Market to which order belongs
price	string	false	Order price
remaining_size	string	false	Remaining size of the order
seq_no	integer	false	Unique increasing number (non-sequential) that is assigned to this order update. Can be used to deduplicate multiple feeds
side	responses.OrderSide	false	Order side
size	string	false	Order size
status	responses.OrderStatus	false	Order status
stp	responses.STPMode	false	Self Trade Prevention mode (EXEPIRE_MAKER, EXPIRE_TAKER, EXPIRE_BOTH)
timestamp	integer	false	Order signature timestamp
type	responses.OrderType	false	Order type

responses.OrderSide

"BUY"

Properties

Name	Type	Required	Description
anonymous	string	false	none

Enumerated Values

Property	Value
anonymous	BUY
anonymous	SELL

responses.OrderStatus

"NEW"

Properties

Name	Type	Required	Description
anonymous	string	false	none

Enumerated Values

Property	Value
anonymous	NEW
anonymous	OPEN
anonymous	CLOSED

responses.OrderType

"MARKET"

Properties

Name	Type	Required	Description
anonymous	string	false	none

Enumerated Values

Property	Value
anonymous	MARKET
anonymous	LIMIT

responses.PositionResp

{
  "average_entry_price": "29001.34",
  "average_entry_price_usd": "29001.34",
  "cached_funding_index": "1234.3",
  "cost": "-10005.4623",
  "cost_usd": "-10005.4623",
  "id": "1234234",
  "last_fill_id": "1234234",
  "last_updated_at": 1681493939981,
  "market": "BTC-USD-PERP",
  "realized_pnl": "1234.3",
  "seq_no": 1681471234972000000,
  "side": "SHORT",
  "size": "-0.345",
  "status": "OPEN",
  "unrealized_funding_pnl": "12.234",
  "unrealized_pnl": "-123.23"
}

Properties

Name	Type	Required	Description
average_entry_price	string	false	Average entry price
average_entry_price_usd	string	false	Average entry price in USD
cached_funding_index	string	false	Position cached funding index
cost	string	false	Position cost
cost_usd	string	false	Position cost in USD
id	string	false	Unique string ID for the position
last_fill_id	string	false	Last fill ID to which the position is referring
last_updated_at	integer	false	Position last update time
market	string	false	Market for position
realized_pnl	string	false	Realized PNL for the user position
seq_no	integer	false	Unique increasing number (non-sequential) that is assigned to this position update. Can be used to deduplicate multiple feeds
side	string	false	Position Side : Long or Short
size	string	false	Size of the position with sign (positive if long or negative if short)
status	string	false	Status of Position : Open or Closed
unrealized_funding_pnl	string	false	Unrealized running funding P&L for the position
unrealized_pnl	string	false	Unrealized P&L of the position in the quote asset

Enumerated Values

Property	Value
side	SHORT
side	LONG
status	OPEN
status	CLOSED

responses.STPMode

"EXPIRE_MAKER"

Properties

Name	Type	Required	Description
anonymous	string	false	none

Enumerated Values

Property	Value
anonymous	EXPIRE_MAKER
anonymous	EXPIRE_TAKER
anonymous	EXPIRE_BOTH

responses.SystemConfigResponse

{
  "block_explorer_url": "https://voyager.testnet.paradex.trade/",
  "bridged_tokens": [
    {
      "decimals": 0,
      "l1_bridge_address": "string",
      "l1_token_address": "string",
      "l2_bridge_address": "string",
      "l2_token_address": "string",
      "name": "string",
      "symbol": "string"
    }
  ],
  "l1_chain_id": "5",
  "l1_core_contract_address": "0x182FE62c57461d4c5Ab1aE6F04f1D51aA1607daf",
  "l1_operator_address": "0x63e762538C70442758Fd622116d817761c94FD6A",
  "liquidation_fee": "0.20",
  "oracle_address": "0x47c622ce5f7ff7fa17725df596f4f506364e49be0621eb142a75b44ee3689c6",
  "paraclear_account_hash": "0x033434ad846cdd5f23eb73ff09fe6fddd568284a0fb7d1be20ee482f044dabe2",
  "paraclear_account_proxy_hash": "0x3530cc4759d78042f1b543bf797f5f3d647cde0388c33734cf91b7f7b9314a9",
  "paraclear_address": "0x4638e3041366aa71720be63e32e53e1223316c7f0d56f7aa617542ed1e7554d",
  "paraclear_decimals": 0,
  "starknet_chain_id": "SN_CHAIN_ID",
  "starknet_gateway_url": "https://potc-testnet-02.starknet.io"
}

Properties

Name	Type	Required	Description
block_explorer_url	string	false	Block explorer URL for the current SN Instance
bridged_tokens	[responses.BridgedToken]	false	bridged tokens config https://github.com/starknet-io/starknet-addresses/blob/master/bridged_tokens/goerli.json
l1_chain_id	string	false	L1 chain ID value
l1_core_contract_address	string	false	Address of Starknet L1 core contract
l1_operator_address	string	false	Address of Starknet L1 operator
liquidation_fee	string	false	Liquidation fee
oracle_address	string	false	Oracle contract address
paraclear_account_hash	string	false	Class hash of the account contract
paraclear_account_proxy_hash	string	false	Proxy hash of the account contract
paraclear_address	string	false	Paraclear contract address
paraclear_decimals	integer	false	none
starknet_chain_id	string	false	Chain ID for the Starknet Instance
starknet_gateway_url	string	false	Feeder Gateway URL from Starknet

responses.SystemStateResponse

{
  "status": "ok"
}

Properties

Name	Type	Required	Description
status	responses.SystemStatus	false	Status of the system

responses.SystemStatus

"ok"

Properties

Name	Type	Required	Description
anonymous	string	false	none

Enumerated Values

Property	Value
anonymous	ok
anonymous	paused

responses.SystemTimeResponse

{
  "server_time": "1681493415023"
}

Properties

Name	Type	Required	Description
server_time	string	false	Paradex Server time

responses.TradeResult

{
  "created_at": 1681497002041,
  "id": "12345643",
  "market": "BTC-USD-PERP",
  "price": "30001.2",
  "side": "BUY",
  "size": "0.01"
}

Properties

Name	Type	Required	Description
created_at	integer	false	Unix Millisecond timestamp at which trade was done
id	string	false	Unique Trade ID
market	string	false	Market for which trade was done
price	string	false	Trade price
side	responses.OrderSide	false	Taker side
size	string	false	Trade size

responses.TradebustResult

{
  "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
  "busted_fill_id": "12342345",
  "created_at": 1681497002041
}

Properties

Name	Type	Required	Description
account	string	false	Starknet Account from which fill was created
busted_fill_id	string	false	Unique string ID of the busted fill
created_at	integer	false	Unix Millis timestamp when bust was created

responses.TraderRole

"TAKER"

Properties

Name	Type	Required	Description
anonymous	string	false	none

Enumerated Values

Property	Value
anonymous	TAKER
anonymous	MAKER

responses.TransactionResponse

{
  "completed_at": 0,
  "created_at": 0,
  "hash": "0x445c05d6bfb899e39338440d199971c4d7f4cde7878ed3888df3f716efb8df2",
  "id": "12342423",
  "state": "ACCEPTED_ON_L1",
  "type": "TRANSACTION_LIQUIDATE"
}

Properties

Name	Type	Required	Description
completed_at	integer	false	Timestamp from when the transaction was completed
created_at	integer	false	Timestamp from when the transaction was sent to blockchain gateway
hash	string	false	Tx Hash of the settled trade // Hash of the transaction
id	string	false	Unique string ID of the event that triggered the transaction. For example, fill ID or liquidation ID
state	string	false	Status of the transaction on Starknet
type	string	false	Event that triggered the transaction

Enumerated Values

Property	Value
state	ACCEPTED_ON_L1
state	ACCEPTED_ON_L2
state	NOT_RECEIVED
state	PENDING
state	RECEIVED
state	REJECTED
type	TRANSACTION_LIQUIDATE
type	TRANSACTION_FILL

responses.TransferKind

"DEPOSIT"

Properties

Name	Type	Required	Description
anonymous	string	false	none

Enumerated Values

Property	Value
anonymous	DEPOSIT
anonymous	WITHDRAWAL

responses.TransferResult

{
  "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
  "amount": "100",
  "created_at": 1681497002041,
  "id": "123456789",
  "kind": "DEPOSIT",
  "last_updated_at": 1681497002041,
  "socialized_loss_factor": "0",
  "status": "PENDING",
  "token": "USDC",
  "txn_hash": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
  "txn_hash_l1": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa"
}

TransferResult

Properties

Name	Type	Required	Description
account	string	false	Starknet Account address
amount	string	false	Transferred amount
created_at	integer	false	Unix Millis timestamp transfer was created on L2
id	string	false	Transfer auto-generated ID
kind	responses.TransferKind	false	Transfer Kind (DEPOSIT, WITHDRAWAL)
last_updated_at	integer	false	Unix Millis timestamp transfer was last updated on L2
socialized_loss_factor	string	false	Withdrawal's socialized loss factor
status	responses.TransferStatus	false	Transfer External State (PENDING, AVAILABLE, COMPLETED, FAILED)
token	string	false	Transferred token name
txn_hash	string	false	Hash of the L2 transaction that calls Paraclear contract
txn_hash_l1	string	false	Hash of the L1 transaction

responses.TransferStatus

"PENDING"

Properties

Name	Type	Required	Description
anonymous	string	false	none

Enumerated Values

Property	Value
anonymous	PENDING
anonymous	AVAILABLE
anonymous	COMPLETED
anonymous	FAILED

WebSocket JSON-RPC API

Server URLs

Testnet (Goerli) URL: wss://ws.api.testnet.paradex.trade/v1
Mainnet URL: wss://ws.api.prod.paradex.trade/v1

Establish a WebSocket connection

To establish a WebSocket (WSS) connection on the command line shell, make sure you have NodeJS installed locally before trying.

When running Python-based code, Python 3.10+ is recommended.

Install dependencies

pip install websocket-client

npm install -g wscat

Test a WebSocket connection

import websocket
import json

websocket_url = "wss://ws.api.testnet.paradex.trade/v1"

# Define a callback to check connection success
def on_open(ws):
    print('Connected')

# Connect to the WebSocket server
ws = websocket.WebSocketApp(websocket_url, on_open=on_open)

# Wait for a response
ws.run_forever()

wscat -c wss://ws.api.testnet.paradex.trade/v1

Successful connection

Connected

Connected (press CTRL+C to quit)

Public vs Private channels

Public channels publish information about exchange that is not specific to a particular account. For example: market summary, order book, trades, etc. You do not need to authenticate your account to subscribe to public channels. Private channels publish information about a particular account. You need to authenticate to subscribe to private channels.

Authenticate the WebSocket connection

`auth`

Authenticating before subscribing to channels

import websocket
import json

websocket_url = "wss://ws.api.testnet.paradex.trade/v1"

# Define the message to send
message = {
  "jsonrpc": "2.0",
  "method": "auth",
  "params": {
    "bearer": "JWcgwMbK0bx1uFFef0Lri35ZDwypmCG0isuBv"
  },
  "id": 0
}

# Define a callback to check connection success
def on_open(ws):
    # Send the message
    ws.send(json.dumps(message))

# Define a callback to handle the response
def on_message(ws, message):
    response = json.loads(message)
    print(response)

# Connect to the WebSocket server
ws = websocket.WebSocketApp(websocket_url, on_open=on_open, on_message=on_message)

# Wait for a response
ws.run_forever()

wscat -c wss://ws.api.testnet.paradex.trade/v1
> Connected (press CTRL+C to quit)
> {
  "jsonrpc": "2.0",
  "method": "auth",
  "params": {
    "bearer": "JWcgwMbK0bx1uFFef0Lri35ZDwypmCG0isuBv"
  },
  "id": 0
}

Example Response

{
  "jsonrpc": "2.0",
  "result": {},
  "usIn": 1682556415569005368,
  "usDiff":1291796,
  "id": 0
}

< {
  "jsonrpc": "2.0",
  "result": {},
  "usIn": 1682556415569005368,
  "usDiff":1291796,
  "id": 0
}

Authentication is required in order to subscribe to private channels.
The JWT (bearer) string is obtained from the POST /auth endpoint.

Note: After the initial authentication, users do not need to re-authenticate their WebSocket connection for the lifetime of the connection.

Params

Param	Type	Description	Required
`bearer`	string	JWT string	Yes

Result

Empty

`subscribe`

Subscribing to trades.ETH-USD-PERP channel

import websocket
import json

websocket_url = "wss://ws.api.testnet.paradex.trade/v1"

# Define the message to send
auth = {
  "jsonrpc": "2.0",
  "method": "auth",
  "params": {
    "bearer": "JWcgwMbK0bx1uFFef0Lri35ZDwypmCG0isuBv"
  },
  "id": 0
}
message = {
  "jsonrpc": "2.0",
  "method": "subscribe",
  "params": {
    "channel": "trades.ETH-USD-PERP"
  },
  "id": 1
}

# Define a callback to check connection success
def on_open(ws):
    # Auth first
    ws.send(json.dumps(auth))
    # Send the message
    ws.send(json.dumps(message))

# Define a callback to handle the response
def on_message(ws, message):
    response = json.loads(message)
    print(response)

# Connect to the WebSocket server
ws = websocket.WebSocketApp(websocket_url, on_open=on_open, on_message=on_message)

# Wait for a response
ws.run_forever()

wscat -c wss://ws.api.testnet.paradex.trade/v1
> Connected (press CTRL+C to quit)
> {
  "jsonrpc": "2.0",
  "method": "subscribe",
  "params": {
    "channel": "trades.ETH-USD-PERP"
  },
  "id": 1
}

Example response

{
  "jsonrpc": "2.0",
  "result": {
    "channel": "trades.ETH-USD-PERP"
  },
  "usIn": 1682556415569005368,
  "usDiff":1291796,
  "id": 1
}

< {
  "jsonrpc": "2.0",
  "result": {
    "channel": "trades.ETH-USD-PERP"
  },
  "usIn": 1682556415569005368,
  "usDiff":1291796,
  "id": 1
}

Multiple calls to subscribe can be made, each for a different channel.

Subscribing to the same channel more than once will return an error.

Refer to the WebSocket Channels documentation for a list of supported channels.

Params

Param	Type	Description	Required
`channel`	string	Channel name	Yes

Result

Param	Type	Description	Required
`channel`	string	Channel name	Yes

Unsubscribe from a WebSocket channel

`unsubscribe`

Unsubscribing from trades.ETH-USD-PERP channel

import websocket
import json

websocket_url = "wss://ws.api.testnet.paradex.trade/v1"

# Define the message to send
auth = {
  "jsonrpc": "2.0",
  "method": "auth",
  "params": {
    "bearer": "JWcgwMbK0bx1uFFef0Lri35ZDwypmCG0isuBv"
  },
  "id": 0
}
message = {
  "jsonrpc": "2.0",
  "method": "unsubscribe",
  "params": {
    "channel": "trades.ETH-USD-PERP"
  },
  "id": 2
}

# Define a callback to check connection success
def on_open(ws):
    # Auth first
    ws.send(json.dumps(auth))
    # Send the message
    ws.send(json.dumps(message))

# Define a callback to handle the response
def on_message(ws, message):
    response = json.loads(message)
    print(response)

# Connect to the WebSocket server
ws = websocket.WebSocketApp(websocket_url, on_open=on_open, on_message=on_message)

# Wait for a response
ws.run_forever()

wscat -c wss://ws.api.testnet.paradex.trade/v1
> Connected (press CTRL+C to quit)
> {
  "jsonrpc": "2.0",
  "method": "unsubscribe",
  "params": {
    "channel": "trades.ETH-USD-PERP"
  },
  "id": 2
}

Example response

{
  "jsonrpc": "2.0",
  "result": {
    "channel": "trades.ETH-USD-PERP"
  },
  "usIn": 1682556415569005368,
  "usDiff":1291796,
  "id": 2
}

< {
  "jsonrpc": "2.0",
  "result": {
    "channel": "trades.ETH-USD-PERP"
  },
  "usIn": 1682556415569005368,
  "usDiff":1291796,
  "id": 2
}

Unsubscribing from a channel that you are not subscribed to will return an error.

Params

Param	Type	Description	Required
`channel`	string	Channel name	Yes

Result

Param	Type	Description	Required
`channel`	string	Channel name	Yes

WebSocket channels documentation

Channels that can be subscribed to to get real time updates by using subscribe.

Operations

SUB `orders.{market_name}` Operation

Private websocket channel to receive order updates

Parameters

Name	Type	Description	Value	Constraints	Notes
market_name	string	Name of the market or "ALL" to subscribe for updates to all markets	allowed (`"ETH-USD-PERP"`, `"ALL"`)	-	required

Message Order (Private) `order`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	-	-	-	additional properties are NOT allowed
account	string	Account identifier (user's account address)	-	-	-
cancel_reason	string	Reason for order cancellation if it was closed by cancel	allowed (`"USER_CANCELED"`, `"NOT_ENOUGH_MARGIN"`, `"EMPTY_MARKET"`, `"POST_ONLY_WOULD_CROSS"`, `"REMAINING_IOC_CANCEL"`, `"UNEXPECTED_FAILURE"`, `"DELEVERAGE"`, `"IN_LIQUIDATION"`, `"SELF_TRADE"`, `"ASSET_UNAVAILABLE"`, `"ASSET_EXPIRED"`, `"ORDER_TYPE_INVALID"`, `"PRICE_NOT_AVAILABLE"`, `"EXPIRED"`, `"PRICE_OUTSIDE_BANDS"`, `"TIMEOUT"`, `"ORDER_EXCEEDS_POSITION_LIMIT"`)	-	-
client_id	string	Client id passed on order creation	-	-	-
created_at	integer	Order creation time in milliseconds	-	-	-
id	string	Unique order identifier assigned by exchange	-	-	-
instruction	string	Order instruction type, either "GTC", "IOC", or "POST_ONLY"	allowed (`"GTC"`, `"POST_ONLY"`, `"IOC"`)	-	-
last_updated_at	integer	Order last update time in milliseconds. No changes once status=CLOSED	-	-	-
market	string	Symbol of the market	allowed (`"ETH-USD-PERP"`)	-	-
price	string	Order limit price	-	-	-
remaining_size	string	Remaining size of the order	-	-	-
side	string	Order side	allowed (`"BUY"`, `"SELL"`)	-	-
size	string	Order size	-	-	-
status	string	Order status	allowed (`"NEW"`, `"OPEN"`, `"CLOSED"`)	-	-
timestamp	number	-	-	format (`Unix Timestamp (ms)`)	-
type	string	Order type	allowed (`"MARKET"`, `"LIMIT"`)	-	-
seq_no	integer	Sequence number of the order updates	-	-	-
avg_fill_price	string	Average fill price of the order	-	-	-

Examples of payload (generated)

{
  "account": "0x4638e3041366aa71720be63e32e53e1223316c7f0d56f7aa617542ed1e7512x",
  "cancel_reason": "USER_CANCELED",
  "client_id": "x1234",
  "created_at": 0,
  "id": "123456",
  "instruction": "GTC",
  "last_updated_at": 0,
  "market": "ETH-USD-PERP",
  "price": "26000.5",
  "remaining_size": "0",
  "side": "BUY",
  "size": "0.05",
  "status": "NEW",
  "timestamp": 1681462770114,
  "type": "MARKET",
  "seq_no": 20784,
  "avg_fill_price": "26000"
}

SUB `tradebusts` Operation

Private websocket channel to receive fills that are busted by a blockchain

Message Trade Bust `trade_bust`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	Tradebust details	-	-	additional properties are NOT allowed
account	string	Starknet Account from which fill was created	-	-	-
busted_fill_id	string	Unique string ID of the busted fill	-	-	-
created_at	integer	Bust creation time in milliseconds	-	-	-

Examples of payload (generated)

{
  "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
  "busted_fill_id": "12342345",
  "created_at": 0
}

SUB `fills.{market_name}` Operation

Private websocket channel to receive details of fills for specific account

Parameters

Name	Type	Description	Value	Constraints	Notes
market_name	string	Name of the market or "ALL" to subscribe for updates to all markets	allowed (`"ETH-USD-PERP"`, `"ALL"`)	-	required

Message Fill `fill`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	Fill Details	-	-	additional properties are NOT allowed
client_id	string	Unique client assigned ID for the order.	-	-	-
created_at	integer	Fill time in milliseconds.	-	-	-
fee	string	Fee paid by the user in fee_currency	-	-	-
fee_currency	string	Asset that fee is charged in	allowed (`"USDC"`)	-	-
id	string	Unique ID of the fill	-	-	-
liquidity	string	Maker or Taker	allowed (`"TAKER"`, `"MAKER"`)	-	-
market	string	Symbol of the market	allowed (`"ETH-USD-PERP"`)	-	-
order_id	string	Order ID assigned by exchange	-	-	-
price	string	Price at which order was filled	-	-	-
side	string	Order side	allowed (`"BUY"`, `"SELL"`)	-	-
size	string	Size of the fill	-	-	-
remaining_size	string	Remaining size of the order	-	-	-
seq_no	integer	Sequence number of the fill	-	-	-

Examples of payload (generated)

{
  "client_id": "x1234",
  "created_at": 0,
  "fee": "7.56",
  "fee_currency": "USDC",
  "id": "8615262148007718462",
  "liquidity": "TAKER",
  "market": "ETH-USD-PERP",
  "order_id": "1681462103821101699438490000",
  "price": "30000.12",
  "side": "BUY",
  "size": "0.5",
  "remaining_size": "0.7",
  "seq_no": 20784
}

SUB `positions` Operation

Private websocket channel to receive updates when position is changed

Message Position `position`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	Position details	-	-	additional properties are NOT allowed
average_entry_price	string	Average entry price	-	-	-
average_entry_price_usd	string	Average entry price in USD	-	-	-
cached_funding_index	string	Position cached funding index	-	-	-
cost	string	Position cost	-	-	-
cost_usd	string	Position cost in USD	-	-	-
id	string	Unique string ID for the position	-	-	-
last_fill_id	string	Last fill ID to which the position is referring	-	-	-
last_updated_at	integer	Position last update time in milliseconds	-	-	-
market	string	Symbol of the market	allowed (`"ETH-USD-PERP"`)	-	-
realized_pnl	string	Realized P&L for the user position	-	-	-
side	string	Position Side: Long or Short	allowed (`"LONG"`, `"SHORT"`)	-	-
size	string	Size of the position with sign (positive or negative)	-	-	-
status	string	Status of Position: Open or Closed	allowed (`"OPEN"`, `"CLOSED"`)	-	-
unrealized_funding_pnl	string	Unrealized funding P&L for the position in a quote currency (USD)	-	-	-
unrealized_pnl	string	Unrealized P&L of the position in a quote currency (USD)	-	-	-
seq_no	integer	Sequence number of the position updates	-	-	-

Examples of payload (generated)

{
  "average_entry_price": "29001.34",
  "average_entry_price_usd": "29000.34",
  "cached_funding_index": "1234.3",
  "cost": "1234.3",
  "cost_usd": "1234.1",
  "id": "1234234",
  "last_fill_id": "1234234",
  "last_updated_at": 0,
  "market": "ETH-USD-PERP",
  "realized_pnl": "1234.3",
  "side": "LONG",
  "size": "-0.345",
  "status": "OPEN",
  "unrealized_funding_pnl": "12.234",
  "unrealized_pnl": "-123.23",
  "seq_no": 20784
}

SUB `funding_data.{market_name}` Operation

Public websocket channel to receive funding data updates

Parameters

Name	Type	Description	Value	Constraints	Notes
market_name	string	Name of the market or "ALL" to subscribe for updates to all markets	allowed (`"ETH-USD-PERP"`, `"ALL"`)	-	required

Message Funding Data `funding_data`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	Funding Data details	-	-	additional properties are NOT allowed
market	string	Symbol of the market	allowed (`"ETH-USD-PERP"`)	-	-
funding_index	string	Current Funding Index	-	-	-
funding_premium	string	Current Funding Premium: (Mark Price) - (Spot Price)	-	-	-
funding_rate	string	Current 24hr Funding Rate: (Funding Premium) / (Spot Price)	-	-	-
created_at	integer	Funding payments time in milliseconds	-	-	-

Examples of payload (generated)

{
  "market": "ETH-USD-PERP",
  "funding_index": "100.0",
  "funding_premium": "22.4",
  "funding_rate": "0.0034",
  "created_at": 1681471234972
}

SUB `funding_payments.{market_name}` Operation

Private websocket channel to receive funding payments of an account

Parameters

Name	Type	Description	Value	Constraints	Notes
market_name	string	Name of the market or "ALL" to subscribe for updates to all markets	allowed (`"ETH-USD-PERP"`, `"ALL"`)	-	required

Message Funding Payments `funding_payments`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	Funding Payments details	-	-	additional properties are NOT allowed
id	string	Unique string ID for the funding payment	-	-	-
market	string	Symbol of the market	allowed (`"ETH-USD-PERP"`)	-	-
payment	string	Funding Payment in settlement currency	-	-	-
index	string	Funding Index at the moment of payment	-	-	-
fill_id	string	Unique string ID of the fill that triggered the funding payment	-	-	-
created_at	integer	Funding payment time in milliseconds	-	-	-

Examples of payload (generated)

{
  "id": "1234234",
  "market": "ETH-USD-PERP",
  "payment": "-0.00692314",
  "index": "9.17272552",
  "fill_id": "12342345",
  "created_at": 1681471234972
}

SUB `markets_summary` Operation

Public websocket channel for updates of available markets

Message Market Summary `market_summary`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	Market Summary details	-	-	additional properties are NOT allowed
symbol	string	Symbol of the market	allowed (`"ETH-USD-PERP"`)	-	-
oracle_price	string	Computed oracle (Mark) Price for the market	-	-	-
last_traded_price	string	Last traded price for the market	-	-	-
bid	string	Current Best Bid price	-	-	-
ask	string	Current Best Ask price	-	-	-
volume_24	string	Last 24 hour volume in USD	-	-	-
total_volume	any	Total all time volume for the market in USD	-	-	additional properties are allowed
created_at	integer	Market summary creation time in milliseconds	-	-	-
underlying_price	string	Underlying asset (Spot) price	-	-	-
open_interest	string	Open interest in base currency	-	-	-
funding_rate	string	Current 24hr Funding Rate	-	-	-

Examples of payload (generated)

{
  "symbol": "ETH-USD-PERP",
  "oracle_price": "29799.70877478",
  "last_traded_price": "30109.53",
  "bid": "30112.22",
  "ask": "30130.15",
  "volume_24": "47041.0424",
  "total_volume": "141341.0424",
  "created_at": 1681471234972,
  "underlying_price": "1878.41",
  "open_interest": "182.571",
  "funding_rate": "0.3"
}

SUB `account` Operation

Private websocket channel for receiving updates of account status

Message Account `account`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	Account details	-	-	additional properties are NOT allowed
account	string	User's starknet account	-	-	-
account_value	string	Current account value [including unrealized P&Ls] in quote currency (USD)	-	-	-
free_collateral	string	Account value in excess of Initial Margin requirement in quote currency (USD)	-	-	-
initial_margin_requirement	string	Amount of collateral (in USD) required to open the existing positions	-	-	-
maintenance_margin_requirement	string	Amount of collateral (in USD) required to maintain existing positions	-	-	-
margin_cushion	string	Account value in excess of maintenance margin required (in USD)	-	-	-
settlement_asset	string	Settlement asset for the account	allowed (`"USDC"`)	-	-
status	string	Status of the account	allowed (`"ACTIVE"`, `"DELEVERAGE"`, `"LIQUIDATION"`)	-	-
total_collateral	string	Account's total collateral in quote currency (USD)	-	-	-
updated_at	integer	Account last updated time	-	-	-
seq_no	integer	Sequence number of the account updates	-	-	-

Examples of payload (generated)

{
  "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
  "account_value": "136285.06918911",
  "free_collateral": "73276.47229774",
  "initial_margin_requirement": "63008.59689218",
  "maintenance_margin_requirement": "31597.25239676",
  "margin_cushion": "104687.8167956",
  "settlement_asset": "USDC",
  "status": "ACTIVE",
  "total_collateral": "123003.62047353",
  "updated_at": 1681471234972,
  "seq_no": 20784
}

SUB `trades.{market_name}` Operation

Public websocket channel to receive updates on trades in particular market

Parameters

Name	Type	Description	Value	Constraints	Notes
market_name	string	Name of the market or "ALL" to subscribe for updates to all markets	allowed (`"ETH-USD-PERP"`, `"ALL"`)	-	required

Message Trade `trade`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	Trade details	-	-	additional properties are NOT allowed
created_at	integer	Trade time in milliseconds	-	-	-
id	string	Unique Trade ID	-	-	-
market	string	Symbol of the market	allowed (`"ETH-USD-PERP"`)	-	-
price	string	Trade price	-	-	-
side	string	Which side was a Taker	allowed (`"BUY"`, `"SELL"`)	-	-
size	string	Trade size	-	-	-

Examples of payload (generated)

{
  "created_at": 1681471234972,
  "id": "12345643",
  "market": "ETH-USD-PERP",
  "price": "30001.2",
  "side": "BUY",
  "size": "0.01"
}

SUB `transaction` Operation

Private websocket channel for receiving transaction details of fills

Message Transaction `transaction`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	Transaction details	-	-	additional properties are NOT allowed
completed_at	integer	Transaction completion time in milliseconds	-	-	-
created_at	integer	Transaction being sent to blockchain gateway timestamp in milliseconds	-	-	-
hash	string	Tx Hash of the settled trade	-	-	-
id	string	Unique string ID of the event that triggered the transaction. For example, fill ID or liquidation ID	-	-	-
state	string	Status of the transaction on Starknet	allowed (`"ACCEPTED_ON_L1"`, `"ACCEPTED_ON_L2"`, `"NOT_RECEIVED"`, `"PENDING"`, `"RECEIVED"`, `"REJECTED"`)	-	-
type	string	Event that triggered the transaction	allowed (`"TRANSACTION_LIQUIDATE"`, `"TRANSACTION_FILL"`)	-	-

Examples of payload (generated)

{
  "completed_at": 1681471234972,
  "created_at": 1681471234972,
  "hash": "0x445c05d6bfb899e39338440d199971c4d7f4cde7878ed3888df3f716efb8df2",
  "id": "12342423",
  "state": "ACCEPTED_ON_L1",
  "type": "TRANSACTION_LIQUIDATE"
}

SUB `transfers` Operation

Websocket channel for receiving transfer updates

Meaning of each transfer status:

PENDING: L2 txn calling Paraclear contract is in flight: For Withdrawals it's the initial status; refers to the L2 txn status being RECEIVED, PENDING, ACCEPTED_ON_L2. For Deposits refers to L2 txn status being RECEIVED, PENDING.
AVAILABLE: Action is required from user: For Withdrawals refers to L2 txn status being ACCEPTED_ON_L1 and funds available for collection on Ethereum bridge. For Deposits refers to funds being available in the L2 account, ready to be deposited to Paraclear contract.
COMPLETED: Transfer has completed (final state): For Withdrawals funds have been collected and have moved to the requested Ethereum account; refers to L1 bridge withdraw txn status SUCCESS. For Deposits funds have become available in Paradex; refers to the L2 txn status being ACCEPTED_ON_L2.
FAILED: L2 txn calling Paraclear contract failed with REJECTED status. Deposits can be retried when they fail by repeating the L2 txn.

Message Transfer `transfer`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	Transfer details	-	-	additional properties are NOT allowed
account	string	User's starknet account	-	-	-
amount	string	Transfer amount	-	-	-
created_at	integer	Transfer creation timestamp in milliseconds	-	-	-
id	string	Unique string ID of the transfer	-	-	-
kind	string	Kind of tansfer	allowed (`"DEPOSIT"`, `"WITHDRAWAL"`)	-	-
last_updated_at	integer	Timestamp of the last update of transfer status (in milliseconds)	-	-	-
token	string	Token	allowed (`"USDC"`)	-	-
txn_hash	string	Hash of the L2 transaction	-	-	-
txn_hash_l1	string	Hash of the L1 transaction	-	-	-
status	string	Status of the transfer	allowed (`"PENDING"`, `"AVAILABLE"`, `"COMPLETED"`, `"FAILED"`)	-	-
socialized_loss_factor	string	Socialized loss factor, ratio of funds withheld on withdrawal	-	-	-

Examples of payload (generated)

{
  "account": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
  "amount": "100000",
  "created_at": 1681471234972,
  "id": "123456789",
  "kind": "DEPOSIT",
  "last_updated_at": 1681471234972,
  "token": "USDC",
  "txn_hash": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
  "txn_hash_l1": "0x495d2eb5236a12b8b4ad7d3849ce6a203ce21c43f473c248dfd5ce70d9454fa",
  "status": "PENDING",
  "socialized_loss_factor": "0.0001"
}

SUB `order_book.{market_name}` Operation

Public websocket channel for orderbook updates for the specific market

Parameters

Name	Type	Description	Value	Constraints	Notes
market_name	string	Name of the market	allowed (`"ETH-USD-PERP"`)	-	required

Message Order Book `order_book`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	The entire order book	-	-	additional properties are NOT allowed
seq_no	integer	Sequence number of the orderbook	-	-	-
market	string	Symbol of the market	allowed (`"ETH-USD-PERP"`)	-	-
last_updated_at	integer	Last orderbook update time in milliseconds	-	-	-
asks	array>>	List of Ask sizes and prices, sorted by price ascending	-	-	required
asks (single item)	tuple>	Ask quotes	-	-	additional items are allowed
asks.0 (index)	string	Price	-	-	-
asks.1 (index)	string	Size	-	-	-
bids	array>>	List of Bid sizes and prices, sorted by price descending	-	-	required
bids (single item)	tuple>	Bid quotes	-	-	additional items are allowed
bids.0 (index)	string	Price	-	-	-
bids.1 (index)	string	Size	-	-	-

Examples of payload (generated)

{
  "seq_no": 20784,
  "market": "ETH-USD-PERP",
  "last_updated_at": 0,
  "asks": [
    [
      54321.12,
      21.123
    ]
  ],
  "bids": [
    [
      54321.12,
      21.123
    ]
  ]
}

SUB `order_book.{market_name}.deltas` Operation

Public websocket channel for incremental updates of orderbook for the subscribed market. The first message contains the latest snapshot of the entire orderbook, with consequent messages providing the orderbook deltas. Together with a sequence number seq_no, it would be enough to construct a history of the orderbook since connection established.

Parameters

Name	Type	Description	Value	Constraints	Notes
market_name	string	Name of the market	allowed (`"ETH-USD-PERP"`)	-	required

Message Order Book Deltas `order_book.delta`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	The order book deltas	examples (`{"seq_no":20784,"market":"ETH-USD-PERP","last_updated_at":1681462770114,"update_type":"s","deletes":[],"inserts":[{"side":"BUY","price":"1908.2","size":"69.379"},{"side":"BUY","price":"1908.18","size":"16.569"},{"side":"SELL","price":"1909.16","size":"18.465"},{"side":"SELL","price":"1909.89","size":"8.144"}],"updates":[]}`, `{"seq_no":20785,"market":"ETH-USD-PERP","last_updated_at":1681462770115,"update_type":"d","deletes":[{"side":"SELL","price":"1909.16","size":"0"}],"inserts":[],"updates":[{"side":"BUY","price":"1908.2","size":"42.95"}]}`)	-	additional properties are NOT allowed
seq_no	integer	Sequence number of the orderbook deltas	-	-	-
market	string	Symbol of the market	allowed (`"ETH-USD-PERP"`)	-	-
last_updated_at	integer	Last orderbook update time in milliseconds	-	-	-
update_type	string	The type of update message this is. `s` denotes the first message with the full state of orderbook whereas `d` denotes the book delta from the previous `seq_no`.	allowed (`"s"`, `"d"`)	-	-
deletes	array	An array of orders that are no longer in the orderbook. Empty if `update_type` is `s`.	-	-	required
deletes.side	string	-	allowed (`"BUY"`, `"SELL"`)	-	-
deletes.price	string	-	-	>= 0	-
deletes.size	string	-	-	>= 0	-
inserts	array	An array of orders that were added to the orderbook.	-	-	required
inserts.side	string	-	allowed (`"BUY"`, `"SELL"`)	-	-
inserts.price	string	-	-	>= 0	-
inserts.size	string	-	-	>= 0	-
updates	array	An array of order updates (including new orders). Empty if `update_type` is `s`.	-	-	required
updates.side	string	-	allowed (`"BUY"`, `"SELL"`)	-	-
updates.price	string	-	-	>= 0	-
updates.size	string	-	-	>= 0	-

Examples of payload

{
  "seq_no": 20784,
  "market": "ETH-USD-PERP",
  "last_updated_at": 1681462770114,
  "update_type": "s",
  "deletes": [],
  "inserts": [
    {
      "side": "BUY",
      "price": "1908.2",
      "size": "69.379"
    },
    {
      "side": "BUY",
      "price": "1908.18",
      "size": "16.569"
    },
    {
      "side": "SELL",
      "price": "1909.16",
      "size": "18.465"
    },
    {
      "side": "SELL",
      "price": "1909.89",
      "size": "8.144"
    }
  ],
  "updates": []
}

{
  "seq_no": 20785,
  "market": "ETH-USD-PERP",
  "last_updated_at": 1681462770115,
  "update_type": "d",
  "deletes": [
    {
      "side": "SELL",
      "price": "1909.16",
      "size": "0"
    }
  ],
  "inserts": [],
  "updates": [
    {
      "side": "BUY",
      "price": "1908.2",
      "size": "42.95"
    }
  ]
}

SUB `balance_events` Operation

Private websocket channel to receive PnL calculation data

Message Balance Event `balance_event`

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	-	-	-	additional properties are NOT allowed
type	string	The type of the balance event	allowed (`"TRANSACTION_FILL"`)	-	-
fill_id	string	Unique string ID of the fill that triggered the balance event	-	-	-
market	string	Symbol of the market	allowed (`"ETH-USD-PERP"`)	-	-
status	string	Status of the Fill	allowed (`"ON_BLOCKCHAIN"`)	-	-
settlement_asset_balance_before	string	Balance of the settlement asset before the balance event	-	-	-
settlement_asset_balance_after	string	Balance of the settlement asset after the balance event	-	-	-
settlement_asset_price	string	Settlement asset price	-	-	-
funding_index	string	Current Funding Index	-	-	-
realized_pnl	string	Realized P&L for the user position	-	-	-
fees	string	Fees paid by the user in fee_currency	-	-	-
realized_funding	string	Realized funding P&L for the position in a quote currency (USD)	-	-	-
created_at	integer	Unix Millisecond timestamp at which the event occurred	-	-	-

Examples of payload (generated)

{
  "type": "TRANSACTION_FILL",
  "fill_id": "12342345",
  "market": "ETH-USD-PERP",
  "status": "ON_BLOCKCHAIN",
  "settlement_asset_balance_before": "1000",
  "settlement_asset_balance_after": "2000",
  "settlement_asset_price": "100.1",
  "funding_index": "0.123",
  "realized_pnl": "12.34",
  "fees": "0.42",
  "realized_funding": "0.444",
  "created_at": 0
}