--- name: holdmanstacks description: > Use this skill when an external agent has a HoldmanStacks agent API key and needs to inspect its managed account, make x402-paid HTTP requests, or use HoldmanStacks APIs for Hyperliquid, OKX Web3, OKX CEX, or Tiger market and trading operations. --- # HoldmanStacks Agent Account Use the HoldmanStacks backend directly with HTTP requests. Prefer this skill when the user wants an agent to operate an existing HoldmanStacks account with an agent API key instead of building a separate SDK or CLI. ## First-time setup If the user does not have an agent API key yet: 1. Open `https://www.holdmanstacks.fun/login` and sign in. 2. Create an agent. HoldmanStacks provisions its dedicated EVM wallet. 3. Fund the wallet and connect any venue accounts the agent needs. 4. Create an API key for the agent in the dashboard. Do not claim an operation can succeed until the required wallet, balance, API key, policy, and venue connection are ready. Current agent keys start with `hm_agent_`. ## Required values - `BASE_URL`: use `https://api.holdmanstacks.fun` unless the user explicitly provides a different HoldmanStacks backend. - `AGENT_KEY`: the agent bearer key created in HoldmanStacks. Treat `AGENT_KEY` as a secret. Never print it, commit it, include it in a URL, send it to an upstream merchant, or store it in project files. ## Request and response conventions Use this bearer authentication for agent endpoints: ```sh curl -sS "$BASE_URL/agent/me" \ -H "Authorization: Bearer $AGENT_KEY" \ -H "Accept: application/json" ``` For JSON request bodies, add: ```sh -H "Content-Type: application/json" ``` Most successful responses use this wrapper: ```json { "code": 0, "message": "ok", "data": {} } ``` Read the HTTP status and `message` before using `data`. Stop after an authentication, policy, balance, venue-configuration, or validation error; explain the error instead of repeatedly retrying. ## Authorization boundary Market-data and account-inspection requests are read-only. Before an operation that pays, swaps, transfers, withdraws, changes leverage or margin, or creates, amends, closes, or cancels an order: 1. Confirm that the user's current request authorizes that exact action. 2. Summarize the venue, asset or instrument, side, size or amount, price or slippage, destination, and live versus demo mode when applicable. 3. If any material value is missing or ambiguous, ask before sending the call. Never infer permission for a live write from permission to inspect data, fetch a quote, preview an order, or prepare transaction data. ## Capability 1: current agent Use `GET /agent/me` to validate the key and inspect the resolved agent, key metadata, EVM wallet address, status, strategy, and cumulative USDC spending. ```sh curl -sS "$BASE_URL/agent/me" \ -H "Authorization: Bearer $AGENT_KEY" ``` Use this as the first request when account readiness is unknown. ## Capability 2: x402 pay-and-call Use `POST /agent/pay-and-call` to call an HTTP endpoint that may require an x402 payment. The HoldmanStacks backend makes the merchant request, pays from the agent wallet when it receives a supported EVM x402 challenge, applies the agent's USDC payment policy, and records a ledger entry. Body: ```json { "url": "https://merchant.example.com/path", "method": "GET", "headers": { "X-Custom-Header": "value" }, "body": { "query": "ETH price" } } ``` Rules: - `url` must be a full `http://` or `https://` URL. - `method` must be `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. - Pass merchant headers only when required. Never put the HoldmanStacks bearer key or an `Authorization` header inside the merchant `headers` object. - Include `body` only when the merchant endpoint expects one. - The current backend accepts exact-scheme EVM x402 payments and rejects a required payment greater than or equal to `0.1` USDC per call. - A lower active payment mandate may reject the call before payment. - A non-402 merchant response is returned without payment. ```sh curl -sS -X POST "$BASE_URL/agent/pay-and-call" \ -H "Authorization: Bearer $AGENT_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://merchant.example.com/data", "method": "GET" }' ``` Key result fields include `paid`, `requestId`, `payment`, and `merchant`. The merchant body can be JSON, text, or base64, as indicated by `bodyEncoding`. ## Capability 3: Hyperliquid All `/hyperliquid` endpoints resolve the account from `AGENT_KEY`. ### Read operations - `GET /hyperliquid/status`: validate access and resolve the trading account. - `GET /hyperliquid/balances`: fetch balances. Optional query: `address`. - `GET /hyperliquid/open-orders`: list open orders. Optional query: `coin`. - `GET /hyperliquid/markets`: list markets. Required query: `marketType` as `perp` or `spot`; optional `coin`. - `GET /hyperliquid/dex-quotes`: list perp DEX names and quote assets. - `GET /hyperliquid/active-asset-data`: inspect current perp account state. Required query: `coin`. - `GET /hyperliquid/funding`: inspect funding. Required query: `coin`. - `GET /hyperliquid/orderbook`: fetch L2 data. Required query: `coin`; optional `limit` from 1 to 500, `nSigFigs` as 2, 3, 4, or 5, and `mantissa` as 2 or 5. - `GET /hyperliquid/positions`: list current perp positions. - `GET /hyperliquid/fills`: list fills. Optional queries: `coin`, `since`, `limit`, `aggregateByTime`, and `twapFills`. - `GET /hyperliquid/ticker`: fetch a market snapshot. Required queries: `coin` and `marketType` as `perp` or `spot`. Example: ```sh curl -sS "$BASE_URL/hyperliquid/ticker?coin=BTC&marketType=perp" \ -H "Authorization: Bearer $AGENT_KEY" ``` ### Place an order `POST /hyperliquid/order` ```json { "coin": "BTC", "marketType": "perp", "orderType": "limit", "side": "BUY", "size": "0.001", "price": "50000", "reduceOnly": false, "timeInForce": "Gtc" } ``` Rules: - `marketType`: `perp` or `spot`. - `orderType`: `market`, `limit`, `stop_limit`, `stop_market`, or `twap`. - `side`: `BUY` or `SELL`. - `size`, `price`, `triggerPrice`, `tpPrice`, and `slPrice` are positive numeric strings. Supply the price fields required by the chosen order type. - `timeInForce`: optional `Gtc`, `Ioc`, or `Alo`. - `durationMinutes`: optional integer from 5 to 1440 for TWAP flows. - `randomizeSlices` and `reduceOnly` are optional booleans. - Active HoldmanStacks trade mandates are enforced for order placement. ### Manage orders and exposure - `POST /hyperliquid/cancel` with `{"orders":[{"coin":"BTC","orderId":123456}]}`. Up to 100 items. - `POST /hyperliquid/cancel-all` with optional body `{"coin":"BTC"}`. Use an empty object to cancel all supported open orders. - `POST /hyperliquid/set-leverage` with `{"coin":"BTC","leverage":5,"isCross":true}`. - `POST /hyperliquid/update-isolated-margin` with `{"coin":"BTC","action":"add","amount":"10"}`. `action` is `add` or `remove`; this requires an open isolated perp position. - `POST /hyperliquid/transfer` with `{"amount":"10","dex":"","fromPerp":true}`. - `POST /hyperliquid/send` with `{"destination":"0x...","amount":"10","marketType":"spot","asset":"HYPE"}`. The destination must be an EVM address. Perp sends support USDC only. - `POST /hyperliquid/withdraw` with `{"destination":"0x...","amount":"10"}` to withdraw Perps USDC to Arbitrum. Before placing a perp order, prefer reading markets, active asset data, positions, open orders, and the order book. Use `reduceOnly: true` when the user's intent is only to reduce an existing position. ## Capability 4: OKX Web3 token data and EVM swaps These operations use platform-managed OKX Web3 access and the agent's HoldmanStacks EVM wallet. ### Token data - `GET /okx/token/hot-tokens` - `GET /okx/token/all-tokens?chainIndex=1` - `GET /okx/token/search?chains=1,10&search=weth` - `GET /okx/token/toplist?chains=1,10&sortBy=5&timeFrame=4` - `POST /okx/token/basic-info` with an array of token lookup objects. - `POST /okx/token/trading-info` with an array of token lookup objects. - `GET /okx/token/advanced-info?chainIndex=1&tokenContractAddress=0x...` - `GET /okx/token/holders?chainIndex=1&tokenContractAddress=0x...` - `GET /okx/token/liquidity?chainIndex=1&tokenContractAddress=0x...` - `GET /okx/token/trades?chainIndex=1&tokenContractAddress=0x...` - `GET /okx/token/top-traders?chainIndex=1&tokenContractAddress=0x...` Lookup array example: ```json [ { "chainIndex": "1", "tokenContractAddress": "0xC02aaA39b223FE8D0A0E5C4F27eAD9083C756Cc2" } ] ``` ### Quote and prepare a swap - `GET /okx/swap/chains`: list supported chains. - `GET /okx/swap/liquidity?chainIndex=1`: list liquidity sources. - `GET /okx/swap/quote`: requires `chainIndex`, `fromTokenAddress`, `toTokenAddress`, and raw `amount`. - `GET /okx/swap/transaction`: requires the quote fields plus `userWalletAddress`; returns unsigned transaction data. - `GET /okx/swap/approve-transaction`: requires `chainIndex`, `tokenContractAddress`, and raw `approveAmount`. - `POST /okx/swap/check-approvals`: checks token allowances using the upstream OKX request shape. Use `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` for the native EVM token where the OKX API expects its native-token sentinel. Quote example: ```sh curl -sS "$BASE_URL/okx/swap/quote?chainIndex=1&fromTokenAddress=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&toTokenAddress=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&amount=1000000" \ -H "Authorization: Bearer $AGENT_KEY" ``` ### Execute an EVM swap `POST /okx/swap/execute` checks allowance, submits an approval when required, executes the swap from the authenticated agent wallet, waits for receipts, and records the transaction. ```json { "chainIndex": "1", "fromTokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "toTokenAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "readableAmount": "1.5", "gasLevel": "average" } ``` Rules: - Provide exactly one of raw `amount` or human-readable `readableAmount`. - `gasLevel`: optional `slow`, `average`, or `fast`. - `swapMode`: optional `exactIn` or `exactOut`. - `slippagePercent` and `maxAutoSlippagePercent` are optional numeric strings. - Executable chains must be supported EVM mainnets known to the backend. - `tips` and `mevProtection` are not supported for execution. Key result fields include `requestId`, `approveTxHash`, `swapTxHash`, token and amount details, price impact, gas, wallet address, and chain index. ## Capability 5: OKX CEX Use `/okx-cex` only after the user has connected an OKX account to the agent. The backend signs requests with the encrypted credentials belonging to that agent. Query parameters and JSON bodies follow OKX API v5 conventions. ### Market data - `GET /okx-cex/market/ticker` - `GET /okx-cex/market/tickers` - `GET /okx-cex/market/orderbook` - `GET /okx-cex/market/candles` - `GET /okx-cex/market/instruments` - `GET /okx-cex/market/funding-rate` - `GET /okx-cex/market/mark-price` - `GET /okx-cex/market/trades` - `GET /okx-cex/market/index-ticker` - `GET /okx-cex/market/index-candles` - `GET /okx-cex/market/price-limit` - `GET /okx-cex/market/open-interest` ```sh curl -sS "$BASE_URL/okx-cex/market/ticker?instId=BTC-USDT" \ -H "Authorization: Bearer $AGENT_KEY" ``` ### Trading namespaces Use one of `spot`, `swap`, `futures`, or `option` as `{market}`. The backend provides these route patterns: - `GET /okx-cex/{market}/orders` - `GET /okx-cex/{market}/order` - `GET /okx-cex/{market}/positions` - `GET /okx-cex/{market}/fills` - `POST /okx-cex/{market}/order` - `POST /okx-cex/{market}/order/cancel` - `PATCH /okx-cex/{market}/order` - `POST /okx-cex/{market}/orders/batch` - `PATCH /okx-cex/{market}/orders/batch` - `POST /okx-cex/{market}/orders/batch-cancel` - `POST /okx-cex/{market}/close-position` - `POST /okx-cex/{market}/leverage` - `GET /okx-cex/{market}/leverage` - `GET /okx-cex/{market}/algo-orders` - `POST /okx-cex/{market}/algo-order` - `PATCH /okx-cex/{market}/algo-order` - `POST /okx-cex/{market}/algo-orders/cancel` Only use a route when OKX supports that operation for the selected market. Before sending an order, read instrument metadata and account capacity instead of guessing tick size, lot size, margin availability, position mode, or leverage. Spot order example: ```sh curl -sS -X POST "$BASE_URL/okx-cex/spot/order" \ -H "Authorization: Bearer $AGENT_KEY" \ -H "Content-Type: application/json" \ -d '{ "instId": "BTC-USDT", "tdMode": "cash", "side": "buy", "ordType": "limit", "sz": "0.001", "px": "50000" }' ``` ### Option and account helpers - `GET /okx-cex/option/instruments` - `GET /okx-cex/option/greeks` - `POST /okx-cex/account/transfer` - `GET /okx-cex/account/balance` - `GET /okx-cex/account/asset-balance` - `GET /okx-cex/account/config` - `GET /okx-cex/account/trade-fee` - `GET /okx-cex/account/max-size` - `GET /okx-cex/account/max-withdrawal` - `GET /okx-cex/account/max-avail-size` - `GET /okx-cex/account/positions` - `GET /okx-cex/account/positions-history` - `GET /okx-cex/account/bills` - `GET /okx-cex/account/bills-archive` - `POST /okx-cex/account/set-position-mode` Account transfer and position-mode changes are live write operations and need the same explicit authorization as orders. ## Capability 6: Tiger Use `/tiger` only after the user has connected a Tiger account to the agent. ### Read and preview operations - `GET /tiger/market-state?market=US` - `GET /tiger/quotes?symbols=AAPL,TSLA` - `GET /tiger/klines?symbol=AAPL&period=day` - `GET /tiger/timeline?symbols=AAPL,TSLA` - `GET /tiger/positions` - `GET /tiger/assets` - `GET /tiger/orders` - `GET /tiger/active-orders` - `GET /tiger/inactive-orders` - `GET /tiger/filled_orders` - `POST /tiger/preview-order` Preview and order bodies accept: - Required: `action`, `orderType`, `totalQuantity`, `symbol`, and `secType`. - Optional: `limitPrice`, `auxPrice`, `trailingPercent`, `timeInForce`, `outsideRth`, `orderLegs`, `algoParams`, `market`, `currency`, `expiry`, `strike`, `right`, `identifier`, `name`, `remark`, `source`, and `userMark`. Preview example: ```sh curl -sS -X POST "$BASE_URL/tiger/preview-order" \ -H "Authorization: Bearer $AGENT_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "BUY", "orderType": "LMT", "totalQuantity": 1, "symbol": "AAPL", "secType": "STK", "limitPrice": 150, "currency": "USD" }' ``` ### Write operations - `POST /tiger/order`: place an order with the preview body shape. - `PATCH /tiger/order/:id`: modify an order with at least one order field. - `POST /tiger/order/:id/cancel`: cancel an order. Prefer previewing a Tiger order immediately before placement. Do not treat a successful preview as authorization to place the order. ## Final execution check Before any live write, verify: - The bearer key resolves to the intended active agent. - The intended wallet or venue account is funded and connected. - The network, venue, market type, asset or instrument, direction, quantity, price, leverage, slippage, and destination match the user's request. - Relevant balances, positions, open orders, precision, and policy limits have been checked recently. - The user has authorized the exact live action. After a live write, report the backend `requestId`, order ID, or transaction hash when available. Read the resulting order, position, balance, or receipt to confirm the outcome instead of assuming submission means completion.