---
title: Credentials
description: Managed trading wallets now; bring your own key is coming soon.
---

A live deployment trades with the Superior-managed wallet today. BYOK is coming soon.

|              | **Managed wallet** (default)                                                                                                  | **BYOK**                                             |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| What it is   | Superior creates and manages a trading wallet for your account                                                                | You supply your own scoped key                       |
| Custody      | Superior (Privy-secured wallet infrastructure — the same custody that runs the [Terminal](https://terminal.superior.trade)) | Yours, entirely                                      |
| Setup        | None — deposit and deploy                                                                                                     | Coming soon                                          |
| Funding      | Deposit USDC to your account; deploys allocate to the venue automatically                                                     | You fund your own venue account                      |
| Key handling | You never touch a key                                                                                                         | Key injected into your deployment, destroyed with it |
| Status       | Supported now                                                                                                                 | Coming soon                                          |

## Managed wallet (default)

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

```json
{ "credentials": { "type": "managed" } }
```

- The wallet is created on first use and belongs to your account — [Trading Wallet](/wallet/overview) 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.

### PUT /runtime/deployments/:id/credentials

Attach or refresh the managed credential for an owned live deployment. Managed credentials are implemented today; the request accepts only an empty object or `{ "type": "managed" }`. Secret material and credential references are rejected.

**Response — `200`**

```json
{ "attached": true, "type": "managed", "status": "ready" }
```

## BYOK (coming soon)

BYOK is not supported by the live unified API yet. The examples below show the planned API shape only; they are not available for production live deployments. Use the managed wallet until [`/context/venues`](/context/venues) marks BYOK as supported.

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

**Hyperliquid (wallet venue):**

```json
{
  "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 →](/guides/byok-security)

**Lighter (API-key venue):**

```json
{
  "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):**

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

**Response — `200`**

```json
{
  "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:

```json
{
  "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:

```json
{
  "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`](/runtime/deployments) `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)

Planned BYOK credentials will be 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](/reference/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 planned BYOK support, wallet venues will 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 ceremony](/guides/byok-security#the-hyperliquid-ceremony-two-calls); API-key venues such as Lighter will need a scoped exchange credential. [Exchange Authorization](/runtime/exchange-authorization) covers the current managed path and planned BYOK path. With a managed wallet the runtime performs the equivalent setup itself on first deploy. 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`).