Exchange Authorization

The required steps before a live deployment can trade.

Before a live deployment can trade, Superior must prove to the exchange that the deployment is allowed to place orders for the account it will use. The live path today is managed-wallet authorization on Hyperliquid. BYOK and Lighter authorization are coming soon.

Both paths end in the same runtime state: credentials.attached is true, the venue_account readiness probe is healthy, and the deployment can start trading.

Sequence

%%{init: {"sequence": {"wrap": true, "width": 150, "messageMargin": 36, "actorMargin": 56}}}%%
sequenceDiagram
    autonumber
    actor User
    participant API as Superior API
    participant Venue as Exchange

    User->>API: Create live deployment
    User->>API: Select venue + credentials

    alt Managed wallet
        User->>API: Deposit USDC
        API->>API: Prepare account
        API-->>User: Ready status
    else BYOK + Hyperliquid (coming soon)
        User->>Venue: Sign agent approval
        User->>Venue: Sign builder fee
        User->>API: Attach wallet + key
        API->>Venue: Verify approvals
    else BYOK + Lighter (coming soon)
        User->>Venue: Create scoped key
        User->>API: Store credential
        API-->>User: credential_id
        User->>API: Attach credential_id
        API->>Venue: Verify scope
    end

    API->>Venue: Check funding
    User->>API: Start deployment
    API->>Venue: Trade

Flow

1. Choose a credential source for the deployment:
   • Managed wallet: Superior manages the trading wallet and performs supported exchange onboarding during live start.
   • BYOK: Coming soon.
2. Choose the venue:
   • Hyperliquid needs signatures from the owner wallet.
   • Lighter needs exchange API credentials.
3. Complete the venue authorization.
4. Attach or confirm credentials through PUT /runtime/deployments/:id/credentials.
5. Start the deployment. If a step is missing, the start error names the missing requirement instead of failing silently.

Hyperliquid: wallet-signature authorization

Hyperliquid authorizes trading from wallet signatures. The signer is the owner wallet for the account, and the trading key should be an approved agent wallet.

Managed wallet

For { "credentials": { "type": "managed" } }, Superior owns the operational setup:

1. The user deposits USDC into the managed wallet.
2. The runtime allocates funds to Hyperliquid when the live deployment starts.
3. Superior signs the required Hyperliquid setup for the managed venue account:
   • approve the agent wallet that will place orders;
   • authorize the builder fee used by the platform.
4. The deployment starts once funding and venue readiness are confirmed.

The user does not handle a private key in this path.

BYOK (coming soon)

For the planned { "type": "byok", "venue": "hyperliquid" } path, the user keeps custody and signs locally:

1. Create an agent wallet keypair.
2. From the owner wallet, sign Hyperliquid's agent-wallet approval.
3. From the owner wallet, sign the builder-fee approval.
4. Attach the owner wallet address and agent wallet private key:

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

Superior verifies that the key belongs to an approved agent wallet and is not the owner wallet. If verification fails, the deployment remains blocked with a credential-readiness error. The two local signing calls are documented in Key Safety for BYOK.

Lighter: exchange-credential authorization

Lighter authorizes trading through an exchange API credential. The owner wallet stays with the user; the deployment receives only a reference to a scoped credential that was added through the secure credential flow.

Managed wallet

For managed credentials, Superior prepares the account and credential material inside Superior Trade, then verifies the venue is ready:

1. The user deposits USDC into the managed wallet.
2. Superior prepares the Lighter account and API credential material offline inside Superior Trade.
3. Superior returns the prepared account status to the user.
4. The deployment starts after the credential and venue funding checks pass.

BYOK (coming soon)

For the planned { "type": "byok", "venue": "lighter" } path, the user creates the credential on Lighter, adds it through the secure credential flow, and attaches the resulting credential reference to the deployment:

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

Superior verifies that the referenced credential is an API key for the owner account and is suitable for trading authorization. The private credential value is never returned or displayed by the API. Owner keys or credentials with unsafe authority are rejected by default, matching the credential-safety rules in /runtime/credentials.

Runtime readiness

Authorization is checked before trading starts and again when a deployment restarts:

• credentials_missing: no managed authorization is attached. BYOK authorization is coming soon.
• credentials_invalid: the exchange no longer accepts the attached authorization, such as a revoked Hyperliquid agent wallet or Lighter API key.
• account_not_funded: authorization exists, but the venue account does not have enough funds to trade.

When rotating credentials, stop the deployment, replace the credential with PUT /runtime/deployments/:id/credentials, then start it again. Running strategies read authorization material at process start, so hot-swap is not supported.