---
title: Key Safety for BYOK
description: Scoped keys, agent wallets, and the rules that keep custody with you.
---

BYOK is coming soon. This page documents the planned safety model for bring-your-own-key deployments; use the [managed wallet](/wallet/overview) for live deployments until [`/context/venues`](/context/venues) marks BYOK as supported.

Bring-your-own-key means the security model is a partnership: Superior [handles your credential as toxic material](/runtime/credentials#the-toxic-material-rules-byok); you choose *which* credential to hand over. That choice is most of the security.

## Rule one: never send a master key

Every supported venue offers a **scoped trading credential** — a key that can trade but cannot withdraw:

| Venue | Scoped credential | What it can't do |
|---|---|---|
| Hyperliquid | Agent wallet | Withdraw, transfer, change account settings |
| Lighter | Scoped API credential | Withdraw (owner key stays with you) |
| Binance | API key with trade-only permissions | Withdraw (leave the withdrawal permission unchecked) |
| Polymarket | Proxy/trading wallet holding only allocated funds | Touch your main wallet |

If a scoped key leaks — from anywhere, us included — the blast radius is the account you funded, not your wallet. Be precise about what that means: a trade-only key can't withdraw, but an attacker holding it *can* destroy value up to the account balance, including deliberately (trading badly against their own positions to extract it). Scoped keys don't make a leak harmless; they make it **bounded** — which is why the second rule below (fund only what the strategy should command) is part of the security model, not a budgeting tip. That asymmetry is why [`PUT …/credentials`](/runtime/credentials) rejects master credentials by default and requires explicit unsafe-credential acknowledgements for any override.

## Hyperliquid agent wallets in 60 seconds

An agent wallet is a second keypair your master wallet approves on-chain. It signs orders; the venue rejects anything else from it.

The approval must be signed by *your* master key — which is exactly why Superior can't (and shouldn't) do it for you. Sign it locally:

## The Hyperliquid ceremony: two calls

Using the Hyperliquid SDK on your own machine (your master key never leaves it):

```python
# pip install hyperliquid-python-sdk ; runs locally, two signatures, done.
from eth_account import Account
from hyperliquid.exchange import Exchange

master = Account.from_key("0xYOUR_MASTER_KEY")     # stays on this machine
agent = Account.create()                            # the new scoped keypair
ex = Exchange(master)
ex.approve_agent(agent.address)                     # agent can now trade, never withdraw
ex.approve_builder_fee("0x…superior_builder", "0.01%")  # one-time fee authorization

print("agent address:", agent.address)
print("agent key:    ", agent.key.hex())            # -> PUT …/credentials
```

That's the planned ceremony: `approveAgent` + `approveBuilderFee`, then send the **agent** address + key to [`PUT …/credentials`](/runtime/credentials). An official one-command CLI packaging these calls is planned and tracked in the [design log](/reference/design-log).

`scoped_key` verification on our side is a venue lookup, not an assurance: the runtime derives the address from the key you sent and confirms with Hyperliquid that it's an approved agent of `wallet_address` (and *not* the wallet's own key) before it will report `scoped_key: true`.

## Rule two: fund the account, not the strategy's imagination

Deposit only what the strategy should command. The runtime sizes orders from the venue account balance — a scoped key on an account holding $200 is a $200 blast radius, whatever the strategy does. With BYOK, withdrawals remain yours alone: your keys, your venue account, and no Superior endpoint can touch them. (The [managed wallet](/wallet/overview)'s withdrawal endpoint pays out only to your verified login wallet and never applies to BYOK funds.)

## Rule three: rotate like it's free, because it is

- Venue keys: re-run the two-call ceremony to mint a fresh agent key, `PUT` it over the old one, then revoke the old agent on-venue.
- Superior API keys: [rotate without downtime](/account/api-keys#rotation-without-downtime).
- After any incident, rotate both layers; each takes under a minute.

## What Superior can never do with what you gave it

With a scoped BYOK credential and the toxic-material rules together: we can't withdraw (the key can't), can't read your key back to you or anyone (write-only secret store), and can't keep a copy after you delete the deployment (destroyed with the runtime, [confirmed via status](/runtime/deployments)). Concretely, for reviewers who want mechanisms rather than adjectives: strategy workloads run under **gVisor** kernel isolation; BYOK credentials live in the runtime cluster's secret store scoped to your deployment, never in the application database; and the residual risk that remains after all of it is the bounded one stated at the top of this page — bad trades inside the account you chose to fund. Use the managed wallet only when you explicitly want Superior-managed custody for that account.