Authentication

Programmatic access to Parcl is via an API key. The trading UI holds a browser session; bots use an API key.

API keys

Generate an API key from the trading UI. The server holds your signing key in a secure enclave and signs transactions on your behalf when you submit them with the key.

Generating a key

1. Log in at devnet.v4.parcl.co
2. Open Settings (top-right)
3. Click Generate API Key
4. Copy the key immediately. It is shown once and cannot be recovered.

The key format is prcl_sk_<64 hex characters>.

Scope

API keys are scoped to trade-only. A leaked key cannot drain your account.

Submitting a non-allowlisted transaction returns 403. Deposits, withdrawals, and collateral transfers must be done through the trading UI.

Using your key

Authenticated endpoints (/auth/*, /tx/*, account history) live on the REST API host: v4-rest-api.dev.parcllabs.com. Public read endpoints (/v1/markets, /v1/accounts/by-owner/..., /v1/ws) live on the validator host: v4-api.dev.parcllabs.com. See REST API for the host map.

Include the X-API-Key header on every request:

# Read your profile
curl -H "X-API-Key: prcl_sk_abc123..." \
  https://v4-rest-api.dev.parcllabs.com/auth/profile
 
# Place an order (server signs via enclave)
curl -X POST \
  -H "X-API-Key: prcl_sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"transaction":{"PlaceOrder":{"account_id":12,"market_id":0,"side":"Long","order_type":"Market","price":0,"size":100000,"trigger_price":null,"reduce_only":false,"post_only":false,"time_in_force":"IOC","take_profit":null,"stop_loss":null}},"nonce":1713456789000,"timestamp":1713456789}' \
  https://v4-rest-api.dev.parcllabs.com/tx/sign-and-submit
 
# Read your trade history
curl -H "X-API-Key: prcl_sk_abc123..." \
  https://v4-rest-api.dev.parcllabs.com/v1/accounts/12/trades

What happens when you submit a trade

When you send a transaction via POST /tx/sign-and-submit with an API key:

1. The REST API resolves your API key to your user account.
2. The server enforces the trade-only allowlist (see Scope above).
3. Your encrypted signing key is retrieved from the database.
4. The key is decrypted inside a secure enclave and used to sign the transaction.
5. The signed transaction is submitted to the validator.
6. The response includes the transaction result and any events (fills, etc.).

Your signing key never leaves the enclave in plaintext.

Managing your key

• Regenerate: generating a new key immediately invalidates the previous one.
• Revoke: you can revoke your key from Settings without generating a new one.
• One key per account. There is no window where two keys are valid simultaneously.

Security

• Only the SHA-256 hash of your key is stored. If the database leaks, your key cannot be reconstructed.
• The key has 256 bits of entropy (32 random bytes). Brute force is not feasible.
• Treat your API key like a password. Do not commit it to version control or share it.
• If your key is compromised, revoke it from Settings. The trade-only scope limits damage to open positions under your account.

Rate limits

All authenticated requests (API key or JWT) are rate-limited per user:

Exceeding the limit returns HTTP 429 with a Retry-After header.