Key Safety for BYOK

Scoped keys, agent wallets, and the rules that keep custody with you.

Bring-your-own-key means the security model is a partnership: Superior handles your credential as toxic material; 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:

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 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):

# 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 whole ceremony: approveAgent + approveBuilderFee, then send the agent address + key to PUT …/credentials. An official one-command CLI packaging these calls is planned and tracked in the design log — until it ships, the two calls above are the supported path.

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'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.
• 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). 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.