API Authentication

API keys allow you to interact with the Paradex trading system programmatically without using the web interface. This guide covers how to generate and manage different types of credentials for trading, monitoring, and API access.

There are 2 general types of credentials used to authenticate with the Paradex API

1. JWT Tokens - JWT (JSON Web Tokens) are secure tokens that contain encoded information about your permissions. They grant access to most API endpoints that are non-public and are included in every request to the API.
2. Private Keys - Grant full trading access. Private keys are used both for creating JWT Tokens and Signatures, which are both sent to the API to place orders.

Full Trading Access

In order to enable full trading access via API, users need to export a Private Key associated with their account. This can either be:

1. Main Private Key
2. Subkey

Please refer to the SDK documentation on how to use your Private key to interact with on Paradex via API.

• paradex-py
• paradex-js

Private Keys

The account’s Private key can be obtained on the UI on the Wallet tab

Click on ‘Copy Private Key’ to obtain your account’s main private key.

Subkeys

Subkeys are private keys for an account with scoped down permissions. Unlike your main private key, Subkeys do not have permissions to perform Withdrawals, Transfers, and manage sensitive account settings.

However, as private keys, they are still fully capable of creating/modifying orders and interacting with the API.

These keys provide a secure way to delegate trading permissions while maintaining control over account security.

Permissions

Use Cases

• Programmatic Trading: Trade via API without risk of exposing your main Private Key.
• Automated trading bots: Deploy trading strategies without full account access
• Third-party integrations: Allow trusted applications to trade on your behalf
• Team trading: Enable multiple team members to trade with controlled permissions

Creating Subkeys

1. Navigate to account security settings and locate Key Management
2. Click on the ‘Subkeys’ toggle, then click on ’+ Add New Key’

3. Give your subkey a name
4. Generate and securely store your subkey private key. The private key is not stored on the server and will only be shown once.
5. The public key component can be copied on the Subkeys tab. This public key can also be derived from the private key.
6. To revoke a Subkey, click on the Delete button next to the token on the Subkeys tab

Using Subkeys

Subkeys behave like regular private keys. They are used for

• Getting JWT Tokens from the /auth/:public_key endpoint
• Signing requests to create/modify orders

Generating Auth Tokens

While using a subkey:

• The Subkey’s public key must be provided to the auth endpoint /auth/{public_key}
• The PARADEX-STARKNET-ACCOUNT header should be the address of the main account
• The PARADEX-STARKNET-SIGNATURE must be generated by signing using the subkey private key.

EVM Authentication (v2)

Paradex supports onboarding and authentication using EVM wallets via SIWE (Sign-In with Ethereum, ERC-4361) messages. This provides an alternative to the Starknet-based authentication flow.

EVM Onboarding (POST /v2/onboarding)

Onboards a new account using an EVM wallet.

Required headers:

• PARADEX-STARKNET-ACCOUNT — The deterministic Starknet address computed from the ETH address
• PARADEX-EVM-SIGNATURE — EVM personal_sign (EIP-191) signature of the SIWE message
• PARADEX-SIWE-MESSAGE — Base64-encoded SIWE (ERC-4361) message

Request body:

1
{
2
  "public_key": "0x04..."
3
}

• public_key — Uncompressed secp256k1 public key (65 bytes, starting with 0x04)
• referral_code (optional) — Referral code
• marketing_code (optional) — Marketing code

The SIWE onboarding message uses the statement: "Paradex Onboarding".

Example SIWE onboarding message:

app.paradex.trade wants you to sign in with your Ethereum account:
0x1234567890abcdef1234567890abcdef12345678
Paradex Onboarding
URI: https://app.paradex.trade
Version: 1
Chain ID: 1
Nonce: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

The Nonce field is required but can be any randomly generated hex string.

Example pseudocode:

1
# Construct the SIWE onboarding message
2
onboarding_message = f"""app.paradex.trade wants you to sign in with your Ethereum account:
3
{evm_address}
4
5
Paradex Onboarding
6
7
URI: https://app.paradex.trade
8
Version: 1
9
Chain ID: 1
10
Nonce: {random_hex_32}"""
11
12
# Sign with EVM wallet
13
onboarding_signature = personal_sign(onboarding_message, evm_address)
14
15
# POST /v2/onboarding
16
# Headers:
17
#   PARADEX-STARKNET-ACCOUNT: <paradex_account_address>
18
#   PARADEX-EVM-SIGNATURE: <onboarding_signature>
19
#   PARADEX-SIWE-MESSAGE: base64_encode(onboarding_message)
20
# Body: { "public_key": "<uncompressed_secp256k1_public_key>" }

Address computation: The PARADEX-STARKNET-ACCOUNT address is deterministically derived from the ETH address and the EVM account class hash (available from GET /system/config as evm_account_class_hash). The computation follows the standard Starknet contract address formula:

pedersen(PREFIX, deployer=0, salt=ethAddress, classHash, hash(calldata))

EVM Authentication (POST /v2/auth)

Authenticates an existing EVM account and returns a JWT token.

Required headers:

• PARADEX-STARKNET-ACCOUNT — Starknet account address
• PARADEX-EVM-SIGNATURE — EVM personal_sign (EIP-191) signature of the SIWE message
• PARADEX-SIWE-MESSAGE — Base64-encoded SIWE auth message

Optional headers:

• PARADEX-AUTHORIZE-ISOLATED-MARKETS — Authorize all isolated market accounts

Response:

1
{
2
  "jwt_token": "..."
3
}

The JWT token format is the same as Starknet auth. The SIWE auth message includes the expiration time embedded within the message itself (via the expirationTime field), rather than using a separate header.

Example pseudocode:

1
# Construct the SIWE auth message
2
auth_message = f"""app.paradex.trade wants you to sign in with your Ethereum account:
3
{evm_address}
4
5
Paradex Auth
6
7
URI: https://app.paradex.trade
8
Version: 1
9
Chain ID: 1
10
Nonce: {random_hex_32}
11
Issued At: {iso8601_now}
12
Expiration Time: {iso8601_now + 5min}"""
13
14
# Sign with EVM wallet
15
auth_signature = personal_sign(auth_message, evm_address)
16
17
# POST /v2/auth
18
# Headers:
19
#   PARADEX-STARKNET-ACCOUNT: <paradex_account_address>
20
#   PARADEX-EVM-SIGNATURE: <auth_signature>
21
#   PARADEX-SIWE-MESSAGE: base64_encode(auth_message)

EVM Auth with Subkey

EVM accounts use the same Starknet-based subkey authentication as non-EVM accounts. Since subkeys are Starknet keypairs, authenticate with subkeys using the v1 endpoint POST /v1/auth/:pubkey — see Generating Auth Tokens above for details.

Key Differences from Starknet Auth (v1)

Readonly Access

In order to query most APIs with account related information, a JWT Token needs to be attached to the auth headers of the request.

Readonly Tokens

Readonly Tokens are special JWT Tokens with extended expiry dates. Readonly tokens provide secure, read-only access to your account data and market information. These tokens are ideal for building monitoring dashboards, creating trading analytics tools, implementing risk management systems, and developing market data applications.

Since these are JWT tokens, they do not grant trading access. They are also restricted to GET requests and cannot be used to modify account information.

Permissions

Readonly tokens can access most GET endpoints on the API, including:

• Real-time portfolio monitoring and balance information
• Order history and execution status
• Market data and pricing information
• P&L tracking and trade execution details

Creating Readonly Tokens

1. Navigate to account settings and locate the Key Management Section
2. While on the ‘Read-only’ tab, click ”+ Add New Key”

3. Configure key settings (name and expiration)
4. Generate and securely store your API key. Note that this key will only be shown to you once and cannot be recovered after.
5. To revoke a Readonly token, click on the Delete button next to the token on the Read-only tab

Using Readonly Tokens

Readonly tokens can be used just like regular auth tokens in API calls to the platform:

Use your newly generated API token in GET requests to the API

$
curl -X GET "https://api.prod.paradex.trade/v1/balance" \
>
  -H "Authorization: Bearer <READONLY-TOKEN>" \
>
  -H "Content-Type: application/json"

Summary

Paradex offers three main types of API credentials:

• Readonly Tokens: Provide read-only access to account data and market information
• Subkeys: Private keys with trading permissions but restricted from withdrawals and transfers
• Paradex Private Key: This is your account’s main private key. Users with this credential have full access to all account features.

These credentials all enable programmatic access to the Paradex API.

Credential Comparison