bou-wallet

# BOU Wallet Use direct HTTP requests with `curl`. Prefer this skill when the task is to operate this backend through an existing agent bearer key instead of building a separate SDK or CLI first. ## First-time setup after install If the user has installed this skill but does not have an agent API key yet, walk them through this setup first: 1. Open `https://app.bankofuniverse.org/` 2. Sign in, then create an agent in the app 3. Generate the agent API key, then copy it and use it as `AGENT_KEY` in requests If the user has not completed these steps yet, do not pretend the skill can run successfully. First help them obtain a valid `ak_...` key. ## Required inputs Collect these values before making any request: - `BASE_URL`: use `https://api.bankofuniverse.org/` unless the user explicitly gives a different backend - `AGENT_KEY`: bearer token in `ak_...` format Treat the agent key as secret. Do not print, commit, or store it in repo files. ## Common request pattern Use the same bearer auth for all three capability groups. ```sh curl -sS "$BASE_URL/..." \ -H "Authorization: Bearer $AGENT_KEY" \ -H "Accept: application/json" ``` For JSON request bodies, also add: ```sh -H "Content-Type: application/json" ``` Most responses use the shared wrapper: ```json { "code": 0, "message": "", "data": {} } ``` ## Capability 1: x402 pay-and-call Use `POST /agent/pay-and-call` when the agent needs to access an x402-protected upstream URL through this backend. Call this backend endpoint, not the merchant directly. Body shape: ```json { "url": "https://merchant.example.com/path", "method": "GET", "headers": { "X-Custom-Header": "value" }, "body": { "query": "ETH price" } } ``` Rules: - Send a full upstream `http://` or `https://` URL in `url` - Use the upstream HTTP verb in `method` - Pass merchant headers as a JSON object when needed - Pass `body` only when the upstream endpoint expects one - The backend enforces agent status and USDC payment limits before paying - The backend rejects requests when the required payment is `>= 0.1` USDC Example: ```sh curl -sS -X POST "$BASE_URL/agent/pay-and-call" \ -H "Authorization: Bearer $AGENT_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.example.com/search", "method": "POST", "body": { "query": "BTC" } }' ``` ### x402 test cases Use these upstream URLs to quickly test the `pay-and-call` flow. #### Test case 1: random number Upstream endpoint: - `GET /cos/crypto/chainlink/random` Expected response body: ```json { "number": 42 } ``` Example: ```sh curl -sS -X POST "https://api.bankofuniverse.org/agent/pay-and-call" \ -H "Authorization: Bearer $AGENT_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://skills.bankofuniverse.org/cos/crypto/chainlink/random", "method": "GET" }' ``` #### Test case 2: crypto price Upstream endpoint: - `GET /cos/crypto/price/:symbol` Supported symbols: - `ETH` - `BTC` - `USDC` - `USDT` - `TRX` - `BNB` Expected response body: ```json { "symbol": "BTC", "supportedSymbols": ["ETH", "BTC", "USDC", "USDT", "TRX", "BNB"], "price": 84000.12, "timestamp": 1710000000000 } ``` Example: ```sh curl -sS -X POST "https://api.bankofuniverse.org/agent/pay-and-call" \ -H "Authorization: Bearer $AGENT_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://skills.bankofuniverse.org/cos/crypto/price/BTC", "method": "GET" }' ``` ## Capability 2: current agent info Use `GET /agent/me` to inspect the current agent resolved by the bearer key. This endpoint returns the resolved agent, matched API key metadata, cumulative spent USDC, and a best-effort Base USDC balance lookup. Example: ```sh curl -sS "$BASE_URL/agent/me" \ -H "Authorization: Bearer $AGENT_KEY" ``` ## Capability 3: Hyperliquid operations Use the `/hyperliquid` endpoints when the agent needs to inspect or trade through the backend's Hyperliquid integration. All requests use the same bearer auth pattern. ### Read endpoints - `GET /hyperliquid/status` Purpose: verify the current agent is authorized to use Hyperliquid for the resolved account. Key return fields: `address` is the resolved Hyperliquid account address. In agent mode, the response may also include signer-related identity information returned by the backend. Use it when: you want to confirm the bearer key is valid and Hyperliquid access is ready before reading balances or sending orders. - `GET /hyperliquid/balances` Purpose: fetch the latest account balance snapshot from Hyperliquid. Key return fields: `data` contains the balance payload returned by Hyperliquid for the resolved account, including available funds and account balance details. Use it when: you need to check available funds before trading, transferring, or withdrawing. - `GET /hyperliquid/open-orders?coin=BTC` Purpose: list current open orders, optionally filtered by one symbol. Key return fields: each item is normalized to include readable `coin`, `side`, and `marketType`; the rest of the item is the underlying open-order data. Use it when: you want to inspect working orders before canceling or placing another order. - `GET /hyperliquid/markets?marketType=perp` Purpose: list supported spot or perp markets. Key return fields: spot markets include fields such as `coin`, `pairId`, `base`, `quote`, `szDecimals`, `weiDecimals`, and `marketType`; perp markets include fields such as `coin`, `base`, `quote`, `dexName`, `maxLeverage`, `szDecimals`, `onlyIsolated`, `marginMode`, and `marketType`. Use it when: you need to discover valid symbols, decimals, supported dex markets, or leverage-related metadata before trading. - `GET /hyperliquid/active-asset-data?coin=BTC` Purpose: inspect the current account trading state for one perp coin. Key return fields: `coin`, `leverage`, `isCross`, `leverageType`, `maxTradeSzs`, `availableToTrade`, and `markPx`. `maxTradeSzs` and `availableToTrade` are two-element arrays: index `0` is the `BUY` value and index `1` is the `SELL` value. Use it when: you need the current leverage mode, tradeable size, or mark price for a perp coin before placing or sizing an order. - `GET /hyperliquid/funding?coin=BTC` Purpose: fetch current and next funding information for one perp market. Key return fields: `coin`, `fundingRate`, `nextFundingRate`, `nextFundingTimestamp`, `markPrice`, and `indexPrice`. Use it when: you want to evaluate funding cost, expected next funding, or compare mark price with oracle/index price. - `GET /hyperliquid/orderbook?coin=BTC` Purpose: fetch the live L2 order book for one market. Key return fields: `data` is the raw Hyperliquid order book snapshot, including bid and ask levels plus the snapshot time. Use it when: you need market depth, best bid/ask context, or raw book levels for quoting and execution logic. - `GET /hyperliquid/positions` Purpose: list current perp positions across available dex contexts for the account. Key return fields: each position includes `dexName`, `marketType`, `coin`, `szi`, `leverage`, `isCross`, `leverageType`, `entryPx`, `positionValue`, `unrealizedPnl`, `returnOnEquity`, `liquidationPx`, `marginUsed`, `maxLeverage`, and `cumFunding`. Use it when: you want a full view of current exposure, PnL, liquidation risk, and leverage usage. - `GET /hyperliquid/fills?coin=BTC&since=1710000000000&limit=100` Purpose: list historical fills for the account, optionally filtered by symbol, start time, and result count. Key return fields: each fill is normalized to include readable `coin`, `side`, and `marketType`; the rest of the fill fields come from Hyperliquid's fill history. Use it when: you want recent execution history for trade reconciliation, reporting, or strategy logic. - `GET /hyperliquid/ticker?coin=BTC&marketType=perp` Purpose: fetch a compact ticker-style market snapshot for one symbol. Key return fields: `coin`, `marketType`, `last`, `bid`, `ask`, `open`, `close`, `change`, `percentage`, `volume`, `quoteVolume`, and `timestamp`. Use it when: you need a lightweight summary of current price, spread, daily move, and volume without reading the full order book. Query rules: - `marketType`: `perp` or `spot` - `coin`: short asset symbol such as `BTC` or `ETH` - `limit` for fills: `1` to `500` - `nSigFigs` for orderbook: `2`, `3`, `4`, or `5` - `mantissa` for orderbook: `2` or `5` ### Write endpoints - `POST /hyperliquid/order` - `POST /hyperliquid/cancel` - `POST /hyperliquid/cancel-all` - `POST /hyperliquid/set-leverage` - `POST /hyperliquid/transfer` - `POST /hyperliquid/withdraw` #### Place order Request body: ```json { "coin": "BTC", "marketType": "perp", "orderType": "limit", "side": "BUY", "size": "0.001", "price": "50000", "reduceOnly": false, "timeInForce": "Gtc" } ``` Field rules: - `orderType`: `market`, `limit`, `stop_limit`, `stop_market`, or `twap` - `side`: `BUY` or `SELL` - `size`: numeric string - `price`: optional in the DTO, but required for limit-style orders such as `limit` and `stop_limit` - `triggerPrice`: optional in the DTO, but use it for stop orders such as `stop_limit` and `stop_market` - `tpPrice` and `slPrice`: optional take-profit and stop-loss values - `timeInForce`: `Gtc`, `Ioc`, or `Alo` - `durationMinutes`: optional in the DTO, min `5`, max `1440`; use it for TWAP-style flows when required by the backend logic - `randomizeSlices`: optional boolean for TWAP-style flows Example: ```sh curl -sS -X POST "$BASE_URL/hyperliquid/order" \ -H "Authorization: Bearer $AGENT_KEY" \ -H "Content-Type: application/json" \ -d '{ "coin": "BTC", "marketType": "perp", "orderType": "limit", "side": "BUY", "size": "0.001", "price": "50000" }' ``` #### Cancel selected orders Request body: ```json { "orders": [ { "coin": "BTC", "orderId": 123456 } ] } ``` Field rules: - `orders`: required array with at most `100` items - `coin`: required string for each item - `orderId`: required integer for each item, minimum `0` #### Cancel all orders Request body: ```json { "coin": "BTC" } ``` Omit `coin` to cancel all open orders across supported assets. #### Set leverage Request body: ```json { "coin": "BTC", "leverage": 5, "isCross": true } ``` #### Transfer asset Request body: ```json { "amount": "10", "dex": "", "fromPerp": true } ``` Field rules: - `amount`: required numeric string - `dex`: optional dex name string; omit it to use the primary dex. - `fromPerp`: optional boolean, `true` means transfer from perp side #### Withdraw asset Use this endpoint to withdraw Perps USDC to the Arbitrum network. Request body: ```json { "destination": "0x1234567890abcdef1234567890abcdef12345678", "amount": "10" } ``` Field rules: - `destination`: required EVM address - `amount`: required numeric string ## Execution checklist Before running requests: - Verify `BASE_URL` is correct - Verify the token looks like `ak_...` - Verify JSON is valid - Verify Hyperliquid enum values match the accepted casing exactly - Prefer the two built-in x402 test cases above when validating a new agent key - Use `-i` when you need status codes or headers for debugging If a request fails, inspect the wrapped JSON `message` plus the HTTP status first.