API Authentication | Paradex

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

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.
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:

Main Private Key
Subkey

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

For detailed API documentation, see our API Reference.

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.

Access to the Main Private Key grants the ability to Withdraw and Transfer funds from the user’s account. This should never be exposed. For a safer alternative, use Subkeys.

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.

Trading Permissions

Can place and manage orders

Restricted Transfers

Cannot withdraw funds or transfer to other accounts

Account Isolation

Operate within specific account parameters

Enhanced Security

Separate from main account private key

Permissions

Subkeys Can

Place buy and sell orders
Cancel existing orders
Modify order parameters
Access account balance and positions
View order history and trade data
Access market data and pricing

Subkeys Cannot

Withdraw funds from the account
Transfer funds to other accounts
Modify account settings
Manage Subkeys

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

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

Give your subkey a name
Generate and securely store your subkey private key. The private key is not stored on the server and will only be shown once.
The public key component can be copied on the Subkeys tab. This public key can also be derived from the private key.
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.

The main account address is required because subkeys are randomly generated keypairs registered to your account. Since we cannot derive the account address from a subkey’s private key, we must specify which account the subkey belongs to. Additionally, we need to specify the subkey’s public key so it can be used for signature verification instead of defaulting to the main account’s public 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)

Aspect	Starknet (v1)	EVM (v2)
Signature type	Starknet typed data	SIWE (ERC-4361) via `personal_sign`
Public key format	Stark key (`0x` + 64 hex chars)	Uncompressed secp256k1 (`0x04` + 128 hex chars)
Timestamp handling	`PARADEX-TIMESTAMP` header	Embedded in SIWE message (`issuedAt`)
Expiration	`PARADEX-SIGNATURE-EXPIRATION` header	Embedded in SIWE message (`expirationTime`)
Ethereum account	`PARADEX-ETHEREUM-ACCOUNT` header	Derived from public key
Account contract	Cairo 0 proxy pattern	Argent v0.5.0 Cairo 1 (native upgradeability)

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.

Read-only Access

Cannot place orders or modify account settings

Revocable

Can be revoked at any time for security

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

While JWT Tokens have reduced scope, they should still be stored securely and should be rotated regularly.

Creating Readonly Tokens

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

Configure key settings (name and expiration)
Generate and securely store your API key. Note that this key will only be shown to you once and cannot be recovered after.
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

Feature	Readonly Tokens	Subkeys	Private Keys
Access Level	Read-only	Trading only	Full account access
Can Place Orders	❌ No	✅ Yes	✅ Yes
Can Withdraw/Transfer	❌ No	❌ No	✅ Yes
Can Modify Account	❌ No	❌ No	✅ Yes
Authentication Method	Bearer token	Private key signing	Private key signing
Use Cases	Monitoring, analytics	Automated trading	Full account management
Security Risk	Low	Medium	High
Revocable	✅ Yes	✅ Yes	❌ No (requires account migration)

Full Trading Access

Private Keys

Subkeys

Permissions

Subkeys Can

Subkeys Cannot

Use Cases

Creating Subkeys

Using Subkeys

Generating Auth Tokens

EVM Authentication (v2)

EVM Onboarding (POST /v2/onboarding)

EVM Authentication (POST /v2/auth)

EVM Auth with Subkey

Key Differences from Starknet Auth (v1)

Readonly Access

Readonly Tokens

Permissions

Creating Readonly Tokens

Using Readonly Tokens

Summary

Credential Comparison

EVM Onboarding (`POST /v2/onboarding`)

EVM Authentication (`POST /v2/auth`)