Authentication

Parcl offers two paths for programmatic access:

• Agent keys: a keypair you hold and sign with locally, submitting straight to the validator. Non-custodial and lowest-latency. The recommended path for market-making, EMS/venue adapters, autonomous AI trading agents, and any latency-sensitive bot.
• API keys: a token you paste into a tool. Your key signs transactions inside a secure enclave. Higher-latency, for integrations that can't sign locally (webhooks, no-code tools, simple scripts).

Neither can withdraw funds. If your integration can hold a key, use an agent key. This page covers API keys. See Agent keys for the other path.

Non-custodial by design

Parcl is non-custodial. Only you can authorize moving funds off the platform, and Parcl holds no key that can withdraw your funds.

A signing key held inside a secure enclave controls every account. The enclave is an AWS Nitro Enclave, an isolated virtual machine. It has no interactive access, no persistent storage, no operator shell, and no network path except a local channel to relay signing requests. Here is exactly what that gives you:

• Encrypted at rest. Your signing key exists at rest only as ciphertext, encrypted under a key held by AWS KMS. The plaintext key exists only transiently, inside the enclave's memory, for the moment it takes to sign.
• Attestation-gated decryption. KMS releases the decryption key only to an enclave that presents a valid cryptographic attestation. The attestation is a signed measurement of the exact code that the enclave runs. If that code differs in any way, KMS refuses to decrypt. Only the genuine, unmodified enclave can ever recover your key to sign with it.
• Parcl never sees your key. The enclave returns signatures, not the key. The plaintext key is never written to disk, never logged, and never returned to Parcl's servers. It exists only inside the enclave's memory, for the moment it takes to sign.

The consequence is a hard property, not a policy: no Parcl operator, and no party who could compel one, can extract your signing key. The reason is that no copy Parcl can read exists outside the attested enclave, and there is no master key to produce. Parcl cannot move your funds. It can only relay transactions that you authorize.

You can always leave with your key. You can export your signing key through an authenticated browser session. The enclave encrypts it to an ephemeral key that only your browser holds, so the exported key is readable only on your device. Parcl never sees the plaintext, even during export. Export requires a browser session. API keys cannot do it, so a trade-only key can never escalate to key theft. This is what makes the non-custodial design real: you are never dependent on Parcl to reach your account.

Your API key and any agent keys sit on top of this. They authorize software to act for your account within a fixed scope (see Scope). Neither can move funds off the platform. As with any asset you hold with your own keys, your funds are not FDIC-insured or otherwise insured by Parcl.

API keys

Generate an API key from your account settings. The enclave signs transactions when you submit them with your API key.

Generating a key

1. Go to Settings (log in first if you aren't already)
2. Find the API Keys section and click Generate API Key
3. Copy the key immediately. The key appears once. You cannot recover it.

The key format is prcl_sk_<64 hex characters>.

Scope

An API key can do anything your account owner can, with two exceptions. A leaked key cannot move funds off the platform or grant new access.

Submitting a blocked transaction returns 403. Withdrawals and agent-key management require the trading UI (browser session). For lower-latency programmatic trading, use an agent key.

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. The server retrieves your encrypted signing key from the database.
4. A secure enclave decrypts the key and signs the transaction with it.
5. The server submits the signed transaction 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

• The database stores only the SHA-256 hash of your key. If the database leaks, nobody can reconstruct your key.
• 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 leaks, 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.

On-chain request budget

Transaction submission also has an on-chain budget per margin account. Each active account starts with 10,000 standard requests and earns one more request for each USDC of lifetime trading volume. An exhausted account can submit one standard request every 10 seconds. Genuine cancels and reduce-only orders remain available.

Batches consume one budget unit per action. Open-order limits also grow with lifetime volume. These rules apply after the per-user API limit above.

Read the current account state before sending a burst:

curl https://v4-api.dev.parcllabs.com/v1/accounts/12/rate-limit

{
  "accountId": 12,
  "cumulativeVolume": "250000000",
  "requestsUsed": "10040",
  "requestsCap": "10250",
  "requestsSurplus": "210",
  "standardBudgetExempt": false,
  "standardBudgetExemptionReason": null,
  "congestion": {
    "active": false,
    "remaining": null
  }
}

Large counters are decimal strings so JavaScript clients keep full precision. Poll this endpoint through one scheduler per account. Do not start a retry loop for every order in a batch or ladder.

During congestion, a standard request also consumes the account's maker-share quota. The quota is derived from twice the account's prior-day share of total maker volume. FIFO ordering continues after admission. Cancels and genuine reduce-only orders remain available.

Parcl Treasury strategies bypass the lifetime volume-earned gate so protocol-operated books can keep quoting in thin markets. They use the same public endpoint and FIFO mempool and remain subject to ingress limits, open-order caps, and the congestion quota. Community market makers and community vaults use the public formula. Parcl does not assign private limits to community counterparties.

Throttle responses

Transaction throttles return HTTP 429, Retry-After, and machine-readable fields:

{
  "status": "failed",
  "hash": "0x...",
  "events": [],
  "error": "account 12 request budget exhausted; retry after 9321 ms",
  "errorCode": "request_budget_exhausted",
  "retryAfterMs": 9321
}

Treat unknown codes as retriable when the HTTP status is 429. The @parcl/bot-shared manager signer provides a shared account scheduler when it is configured with accountId. It honors these fields.