Credentials

Managed trading wallets by default; bring your own key when you want custody.

A live deployment trades with one of two credential sources — you choose per deployment:

Managed wallet (default)

Omit credentials on create (or pass { "type": "managed" }) and the deployment trades from your account's Superior-managed trading wallet:

{ "credentials": { "type": "managed" } }

• The wallet is created on first use and belongs to your account — Trading Wallet covers deposits, balances, and withdrawals.
• On start, the runtime allocates from your deposited balance to the venue and handles venue onboarding (agent-wallet setup, approvals) for you — the venue_account readiness probe reflects it like any other deployment.
• Withdrawals go back to your verified login wallet only — a hijacked session can't redirect a payout.

BYOK

Attach your own credentials instead — the runtime is non-custodial for these: the key is injected into the deployment's isolated runtime and destroyed when the deployment is deleted.

PUT/runtime/deployments/:id/credentials

Attach (or replace) the credentials a live deployment will trade with. Shape depends on the venue — /context/venues tells you the exact fields.

Hyperliquid (wallet venue):

{
  "type": "byok",
  "venue": "hyperliquid",
  "wallet_address": "0xYourMainWallet…",
  "private_key": "0xAgentWalletPrivateKey…"
}

Send an agent-wallet key, not your master key. A Hyperliquid agent wallet can sign orders but can never withdraw — if the key were ever compromised, your funds still can't leave your account. How to create one →

Lighter (API-key venue):

{ "type": "byok", "venue": "lighter", "owner_address": "0xYourWallet…", "credential_id": "cred_01j..." }

credential_id references a scoped Lighter credential added through the secure credential flow. The API never returns or displays the private credential value.

Binance (CEX):

{ "type": "byok", "venue": "binance", "api_key": "…", "api_secret": "…" }

Response — 200

{ "attached": true, "type": "byok", "wallet_address": "0xYourMainWallet…", "scoped_key": true }

scoped_key: true means the runtime verified the key is a restricted trading key against the venue at PUT time: Hyperliquid — the address derived from your key must appear in the wallet's approved agents (and not equal the wallet itself); Lighter — the key must be an API key, not the owner key; Binance — the key's permissions are read from the venue and must exclude withdrawals. Validity is re-checked at every start (credentials_invalid if the venue has since revoked it).

Unrestricted/master credentials are rejected by default:

{
  "error": {
    "code": "credential_scope_unsafe",
    "message": "Credential can withdraw or controls the owner wallet. Submit a scoped trading key, or set allow_unscoped_credential with the acknowledgement fields."
  }
}

The only unsafe path is machine-visible and deliberate. A client must send all three fields in the same PUT body:

{
  "type": "byok",
  "venue": "hyperliquid",
  "wallet_address": "0xYourMainWallet…",
  "private_key": "0xMasterWalletPrivateKey…",
  "allow_unscoped_credential": true,
  "acknowledge_withdrawal_risk": true,
  "acknowledge_not_recommended": true
}

When accepted, the response still marks the risk: { "attached": true, "scoped_key": false, "warning": "credential_scope_unsafe" }. Agents should not use this override unless a human explicitly requested it for that deployment. The choice stays visible forever after in the deployment’s GET credentials object (metadata only — the secret itself is never returned by any endpoint).

Rotation requires a restart: frameworks read credentials at process start, so hot-swap isn't supported — rotate with stop → PUT → start (seconds of downtime; positions are untouched, and the strategy resumes managing them on restart). There is deliberately no detach endpoint: a credential leaves a deployment only by being replaced (PUT — including switching back to { "type": "managed" }) or destroyed (DELETE of the deployment).

The toxic-material rules (BYOK)

Accepted BYOK credentials are handled as hazardous:

1. Never logged. Request logging redacts the credential fields at the middleware layer, before any handler runs.
2. Never in the database. The secret goes into the runtime cluster's secret store, scoped to your deployment — not the application database. What's queryable is the metadata in the deployment GET. Being precise about the current bar: at-rest envelope encryption and access-audit guarantees for that store are an open design question (design log, OQ 8) and will be resolved and documented before third-party keys are accepted in production — "trust us" is not the final answer here.
3. Encrypted in transit end to end. TLS to the API, encrypted channel to the runtime cluster.
4. Destroyed on delete — and confirmed. DELETE /runtime/deployments/:id removes the credential from that deployment immediately and reports deleted only once destruction is verified (shared-wallet Nautilus runtimes destroy the credential when its last deployment is deleted). There is no orphaned copy to leak later.
5. Replace, don't read. Rotation is a new PUT — there is no way to read a secret back out, for you or for us.

Managed wallets live in Privy's secured wallet infrastructure under Superior's platform controls, not in the deployment secret store — their keys are never exported to you or into strategy config.

Readiness

With BYOK, wallet venues need one-time on-chain setup (Hyperliquid: agent-wallet approval, builder-fee signature) that only your key can sign — two SDK calls make up the whole ceremony; API-key venues such as Lighter need a scoped exchange credential. Exchange Authorization covers both paths end to end. With a managed wallet the runtime performs the equivalent setup itself on first deploy. Either way, the deployment's GET response shows readiness — credentials.attached plus the venue_account funding probe — and start errors name the missing step precisely (credentials_missing vs account_not_funded).