Accept base58 signers + support delegate (API) keys

.env.example

@@ -0,0 +1,15 @@
+# Copy to .env (gitignored) and fill in. Keys are loaded from the environment
+# or a keystore file — never commit them into config/*.toml.
+
+# --- Bullet ---
+# Delegate (API) signer secret. Accepts base58 (Phantom / delegation export),
+# hex (with or without 0x), or use BB_BULLET_KEY_FILE for a Solana JSON keystore.
+# A delegate can only trade (no deposit/withdraw) and is revocable from the webapp.
+BB_BULLET_PRIVATE_KEY=
+
+# Alternatively, point at a Solana-compatible JSON keystore (takes precedence):
+# BB_BULLET_KEY_FILE=/path/to/id.json
+
+# --- Hyperliquid ---
+# API wallet key (secp256k1 hex) created at https://app.hyperliquid.xyz/API.
+BB_HYPERLIQUID_PRIVATE_KEY_HEX=

.gitignore

@@ -7,3 +7,6 @@
 
 # Local/experimental configs — put personal configs here
 config/local/
+
+# Superpowers brainstorming/specs (local working docs)
+docs/superpowers/

AGENTS.md

@@ -55,12 +55,12 @@ Run a bot (default: reads `~/.config/bullet/id.json`):
 cargo run --bin bb-bot -- run --config config/simple-mm-example.toml
 ```
 
-Or point at an explicit keystore / use hex for CI:
+Or point at an explicit keystore / pass a key string for CI:
 
 ```sh
 export BB_BULLET_KEY_FILE="/path/to/keystore.json"   # preferred
-# OR
-export BB_BULLET_PRIVATE_KEY_HEX="0x..."             # fallback
+# OR (base58 from Phantom/delegation export, or hex)
+export BB_BULLET_PRIVATE_KEY="<base58-or-hex>"        # fallback
 ```
 
 ## Architecture — the harness, feeds, and actors
@@ -307,11 +307,15 @@ TOML. Top-level sections: `[engine]`, `[exchanges.<name>]`, `[strategy]`,
   resolves key material in this order (explicit config wins; env fills a
   field the config omits, so an ambient env var can't silently switch
   wallets): `key_file` (in config) → env `BB_BULLET_KEY_FILE` →
-  `private_key_hex` (in config) → env `BB_BULLET_PRIVATE_KEY_HEX`. File-based
-  keystore is preferred — see `bb-bot keygen`. Hyperliquid keys via
-  `BB_HYPERLIQUID_PRIVATE_KEY_HEX`. (Standalone `deposit`/`flatten`/`observe`
-  take no config, so there env is the source: `BB_BULLET_KEY_FILE` → env hex
-  → default keystore.)
+  `private_key` (in config, alias `private_key_hex`) → env
+  `BB_BULLET_PRIVATE_KEY` (alias `BB_BULLET_PRIVATE_KEY_HEX`). The key string
+  may be base58 (Phantom / delegation export) or hex. If the signer is a
+  **delegate** key, the adapter resolves it to its master account (via the
+  `delegateOf` endpoint) for all reads and the user-orders subscription;
+  signing uses the delegate key directly. File-based keystore is preferred —
+  see `bb-bot keygen`. Hyperliquid keys via `BB_HYPERLIQUID_PRIVATE_KEY_HEX`.
+  (Standalone `deposit`/`flatten`/`observe` take no config, so there env is
+  the source: `BB_BULLET_KEY_FILE` → env hex → default keystore.)
 - Strategy configs: `type = "<name>"` with sub-table `[strategy.<name>]`.
 
 ## Code Style

Cargo.toml

@@ -25,6 +25,8 @@ toml = "0.8"
 rust_decimal = { version = "1", features = ["serde-with-str"] }
 thiserror = "2"
 secrecy = { version = "0.8", features = ["serde"] }
+bs58 = "0.5"
+reqwest = { version = "0.13", features = ["json"] }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 async-trait = "0.1"

README.md

@@ -64,13 +64,43 @@ Recommended first path:
 6. `run` — start tiny, watch logs plus `GET /status`.
 7. `flatten` — cancel and close manually if you need to clean up.
 
+## Trading from your own wallet (recommended)
+
+For real usage, trade with a **delegate key** rather than your main wallet key:
+
+1. Sign in at [app.bullet.xyz](https://app.bullet.xyz) (or
+   [app.testnet.bullet.xyz](https://app.testnet.bullet.xyz)) with your wallet
+   (e.g. Phantom). This creates the embedded wallet that is your Bullet trading
+   account.
+2. Deposit collateral through the webapp UI — this initializes the trading
+   account.
+3. Create a delegate (see Bullet's
+   [delegate setup guide](https://docs.bullet.xyz/bulletx-exchange/how-to-guide/delegate-account-setup)),
+   then copy the delegate signer private key into `.env` as
+   `BB_BULLET_PRIVATE_KEY`. Base58 (Phantom / delegation export), hex, and
+   Solana JSON keystores (`BB_BULLET_KEY_FILE`) are all accepted.
+4. For Hyperliquid, create an API wallet at
+   [app.hyperliquid.xyz/API](https://app.hyperliquid.xyz/API) and copy its key
+   into `.env` as `BB_HYPERLIQUID_PRIVATE_KEY_HEX`.
+
+> **What is a delegate / API wallet?** A separate keypair authorized to trade on
+> behalf of your account. It can place and cancel orders but **cannot deposit or
+> withdraw**, and you can revoke it from the webapp at any time — so you trade
+> without exposing your main wallet's private key. The bot resolves the
+> delegate to its master account automatically; all balances and positions live
+> on the master account.
+
+Copy `.env.example` to `.env` (gitignored) to get started.
+
 ## Key management
 
 Private keys are passed via environment variables or keystore files, not copied
 into example configs. Two options:
 
 - **Bullet key file (recommended):** generate once with `cargo run --bin bb-bot -- keygen`, then set `BB_BULLET_KEY_FILE` or add `key_file = "/path/to/id.json"` under `[exchanges.bullet]`.
-- **Hex key:** set `BB_BULLET_PRIVATE_KEY_HEX` / `BB_HYPERLIQUID_PRIVATE_KEY_HEX`, e.g. via a `.env` file (already gitignored).
+- **Key string:** set `BB_BULLET_PRIVATE_KEY` (base58 or hex) /
+  `BB_HYPERLIQUID_PRIVATE_KEY_HEX`, e.g. via a `.env` file (already gitignored).
+  `BB_BULLET_PRIVATE_KEY_HEX` still works as an alias.
 
 ## Strategies
 

config/avellaneda-stoikov-example.toml

@@ -10,7 +10,7 @@ type = "bullet"
 network = "testnet"
 # Key material — do NOT put private keys in this file.
 # Option 1 (preferred): key_file = "/path/to/id.json"  (run `bb-bot keygen`)
-# Option 2 (CI/ephemeral): export BB_BULLET_PRIVATE_KEY_HEX="0x..."
+# Option 2 (CI/ephemeral): export BB_BULLET_PRIVATE_KEY="..." (base58 or hex)
 
 [strategy]
 type = "avellaneda-stoikov"

config/funding-arb-example.toml

@@ -10,7 +10,7 @@ type = "bullet"
 network = "testnet"
 # Key material — do NOT put private keys in this file.
 # Option 1 (preferred): key_file = "/path/to/id.json"  (run `bb-bot keygen`)
-# Option 2 (CI/ephemeral): export BB_BULLET_PRIVATE_KEY_HEX="0x..."
+# Option 2 (CI/ephemeral): export BB_BULLET_PRIVATE_KEY="..." (base58 or hex)
 
 [exchanges.hyperliquid]
 type = "hyperliquid"

config/grid-example.toml

@@ -24,7 +24,7 @@ type = "bullet"
 network = "testnet"
 # Key material — do NOT put private keys in this file.
 # Option 1 (preferred): key_file = "/path/to/id.json"  (run `bb-bot keygen`)
-# Option 2 (CI/ephemeral): export BB_BULLET_PRIVATE_KEY_HEX="0x..."
+# Option 2 (CI/ephemeral): export BB_BULLET_PRIVATE_KEY="..." (base58 or hex)
 
 [strategy]
 type = "grid"

config/reference-arb-example.toml

@@ -16,7 +16,7 @@ status_port = 3032
 [exchanges.bullet]
 type = "bullet"
 network = "testnet"
-# Set via: export BB_BULLET_PRIVATE_KEY_HEX="0x..." or BB_BULLET_KEY_FILE=/path/to/key.json
+# Set via: export BB_BULLET_PRIVATE_KEY="..." (base58 or hex) or BB_BULLET_KEY_FILE=/path/to/key.json
 
 [strategy]
 type = "reference-arb"

config/simple-mm-example.toml

@@ -17,7 +17,7 @@ type = "bullet"
 network = "testnet"
 # Key material — do NOT put private keys in this file.
 # Option 1 (preferred): key_file = "/path/to/id.json"  (run `bb-bot keygen`)
-# Option 2 (CI/ephemeral): export BB_BULLET_PRIVATE_KEY_HEX="0x..."
+# Option 2 (CI/ephemeral): export BB_BULLET_PRIVATE_KEY="..." (base58 or hex)
 
 [strategy]
 type = "simple-mm"

crates/bb-bot/src/main.rs

@@ -158,9 +158,11 @@ fn load_config(path: &str) -> Result<AppConfig, Box<dyn std::error::Error>> {
             table.insert("key_file".to_string(), toml::Value::String(path));
         }
         if table.get("private_key_hex").and_then(toml::Value::as_str).is_none_or(str::is_empty)
-            && let Ok(key) = std::env::var("BB_BULLET_PRIVATE_KEY_HEX")
+            && table.get("private_key").and_then(toml::Value::as_str).is_none_or(str::is_empty)
+            && let Ok(key) = std::env::var("BB_BULLET_PRIVATE_KEY")
+                .or_else(|_| std::env::var("BB_BULLET_PRIVATE_KEY_HEX"))
         {
-            table.insert("private_key_hex".to_string(), toml::Value::String(key));
+            table.insert("private_key".to_string(), toml::Value::String(key));
         }
     }
     if let Some(hl) = config.exchanges.get_mut("hyperliquid")
@@ -523,14 +525,17 @@ fn set_keystore_permissions(_path: &std::path::Path) -> std::io::Result<()> {
 
 /// Resolve a Keypair for standalone (non-harness) commands like `deposit`,
 /// in the same preference order as `BulletConfig`: `BB_BULLET_KEY_FILE` wins,
-/// then `BB_BULLET_PRIVATE_KEY_HEX`, then the default path, else error.
+/// then `BB_BULLET_PRIVATE_KEY` (preferred) or `BB_BULLET_PRIVATE_KEY_HEX` (fallback), then the
+/// default path, else error.
 fn load_deposit_keypair() -> Result<Keypair, Box<dyn std::error::Error>> {
     if let Ok(path) = std::env::var("BB_BULLET_KEY_FILE") {
         return Keypair::read_from_file(&path)
             .map_err(|e| format!("Failed to load keystore {path}: {e}").into());
     }
-    if let Ok(hex) = std::env::var("BB_BULLET_PRIVATE_KEY_HEX") {
-        return Keypair::from_hex(&hex).map_err(Into::into);
+    if let Ok(secret) = std::env::var("BB_BULLET_PRIVATE_KEY")
+        .or_else(|_| std::env::var("BB_BULLET_PRIVATE_KEY_HEX"))
+    {
+        return bb_exchange_bullet::key::keypair_from_secret(&secret).map_err(Into::into);
     }
     let default = default_key_path();
     if default.exists() {
@@ -560,15 +565,17 @@ fn parse_network(s: &str) -> Result<Network, bb_core::error::BotError> {
 /// Build a [`BulletConfig`] for standalone commands (`flatten` / `observe`)
 /// that don't load a TOML config. Resolves key material the same way as
 /// `connect_bullet` / `load_deposit_keypair`: `BB_BULLET_KEY_FILE` env wins,
-/// else the default `~/.config/bullet/id.json` keystore if it exists, with the
-/// `BB_BULLET_PRIVATE_KEY_HEX` env as a fallback. This lets a user who ran
-/// `bb-bot keygen` (which writes the default keystore) use these commands with
-/// no extra env setup. `connect_bullet` enforces that at least one source
+/// else `BB_BULLET_PRIVATE_KEY` (preferred) or `BB_BULLET_PRIVATE_KEY_HEX` (fallback),
+/// else the default `~/.config/bullet/id.json` keystore if it exists.
+/// This lets a user who ran `bb-bot keygen` (which writes the default keystore) use these commands
+/// with no extra env setup. `connect_bullet` enforces that at least one source
 /// yields usable key material.
 fn bullet_config_from_env(network: String) -> BulletConfig {
     use secrecy::SecretString;
 
-    let private_key_hex = std::env::var("BB_BULLET_PRIVATE_KEY_HEX").unwrap_or_default();
+    let private_key_hex = std::env::var("BB_BULLET_PRIVATE_KEY")
+        .or_else(|_| std::env::var("BB_BULLET_PRIVATE_KEY_HEX"))
+        .unwrap_or_default();
     let key_file = std::env::var_os("BB_BULLET_KEY_FILE").map(Into::into).or_else(|| {
         // Only fall back to the default keystore when no hex key was supplied,
         // matching `load_deposit_keypair`'s precedence (env key_file → env hex →

crates/exchanges/bullet/Cargo.toml

@@ -18,6 +18,8 @@ rust_decimal = { workspace = true }
 secrecy = { workspace = true }
 tracing = { workspace = true }
 async-trait = { workspace = true }
+bs58 = { workspace = true }
+reqwest = { workspace = true }
 
 [dev-dependencies]
 toml = { workspace = true }

crates/exchanges/bullet/src/broker.rs

@@ -32,17 +32,19 @@ pub(crate) struct Increments {
 
 pub struct BulletBroker {
     client: Arc<Client>,
+    account_address: String,
     increments: HashMap<String, Increments>,
     health: Arc<ConnectionHealth>,
 }
 
 impl BulletBroker {
     pub(crate) fn new(
         client: Arc<Client>,
+        account_address: String,
         increments: HashMap<String, Increments>,
         health: Arc<ConnectionHealth>,
     ) -> Self {
-        Self { client, increments, health }
+        Self { client, account_address, increments, health }
     }
 
     fn market_id(&self, symbol: &str) -> Result<MarketId, BotError> {
@@ -114,7 +116,12 @@ impl Broker for BulletBroker {
     }
 
     async fn get_balances(&self) -> Result<Vec<Balance>, BotError> {
-        let resp = self.client.my_balances().await.map_err(|e| BotError::exchange(e, true))?;
+        let resp = self
+            .client
+            .account_balance(&self.account_address)
+            .await
+            .map_err(|e| BotError::exchange(e, true))?
+            .into_inner();
         Ok(resp
             .iter()
             .map(|b| Balance {
@@ -126,7 +133,12 @@ impl Broker for BulletBroker {
     }
 
     async fn get_positions(&self) -> Result<Vec<Position>, BotError> {
-        let resp = self.client.my_account().await.map_err(|e| BotError::exchange(e, true))?;
+        let resp = self
+            .client
+            .account_info(&self.account_address)
+            .await
+            .map_err(|e| BotError::exchange(e, true))?
+            .into_inner();
         Ok(resp
             .positions
             .iter()
@@ -146,8 +158,12 @@ impl Broker for BulletBroker {
     }
 
     async fn get_open_orders(&self, symbol: &str) -> Result<Vec<Order>, BotError> {
-        let resp =
-            self.client.my_open_orders(symbol).await.map_err(|e| BotError::exchange(e, true))?;
+        let resp = self
+            .client
+            .query_open_orders(&self.account_address, Some(symbol))
+            .await
+            .map_err(|e| BotError::exchange(e, true))?
+            .into_inner();
         Ok(resp
             .iter()
             .map(|o| {

crates/exchanges/bullet/src/config.rs

@@ -14,10 +14,10 @@ use serde::Deserialize;
 ///    filesystem enforces, never hits the shell history, and isn't trivially exfiltrated via a
 ///    process environment dump.
 /// 2. **`BB_BULLET_KEY_FILE`** (env) — same keystore-file path, supplied via the environment.
-/// 3. **`private_key_hex`** (config) — Ed25519 secret as a hex string. Wrapped in [`SecretString`]
-///    so it's redacted in `Debug` output and zeroed on drop.
-/// 4. **`BB_BULLET_PRIVATE_KEY_HEX`** (env) — Ed25519 secret as a hex string, for CI / ephemeral
-///    contexts.
+/// 3. **`private_key`** (config, alias `private_key_hex`) — Ed25519 secret as a **hex or base58**
+///    string. Wrapped in [`SecretString`] so it's redacted in `Debug` output and zeroed on drop.
+/// 4. **`BB_BULLET_PRIVATE_KEY`** (env, alias `BB_BULLET_PRIVATE_KEY_HEX`) — Ed25519 secret as a
+///    hex or base58 string, for CI / ephemeral contexts.
 #[derive(Debug, Clone, Deserialize)]
 pub struct BulletConfig {
     /// Network to connect to: "mainnet" or "testnet".
@@ -28,9 +28,10 @@ pub struct BulletConfig {
     #[serde(default)]
     pub key_file: Option<PathBuf>,
 
-    /// Ed25519 private key as hex string (with or without "0x" prefix).
+    /// Ed25519 private key as a hex **or base58** string (with or without "0x"
+    /// prefix for hex). Accepts the TOML key `private_key` or `private_key_hex`.
     /// Only used if `key_file` is not set.
-    #[serde(default = "default_secret")]
+    #[serde(default = "default_secret", alias = "private_key")]
     pub private_key_hex: SecretString,
 }
 
@@ -88,4 +89,16 @@ mod tests {
         assert_eq!(cfg.private_key_hex.expose_secret(), "");
         assert!(cfg.key_file.is_none());
     }
+
+    #[test]
+    fn deserializes_private_key_alias() {
+        let toml_src = format!(
+            r#"
+            network = "testnet"
+            private_key = "{FAKE_KEY}"
+        "#
+        );
+        let cfg: BulletConfig = toml::from_str(&toml_src).expect("parse");
+        assert_eq!(cfg.private_key_hex.expose_secret(), FAKE_KEY);
+    }
 }