# Tesseract

> Privy owner wallets and scoped Hyperliquid trading tools for custom bots and AI agents. Self-service accounts support paper simulation and Hyperliquid testnet. Read /api/health for enabled execution modes. Mainnet is explicitly enabled by the deployment and uses real funds with fresh, owner-approved mainnet credentials.

Connect to `/mcp` using stateless Streamable HTTP and `Authorization: Bearer YOUR_AGENT_TOKEN`. The owner first signs in with Privy, creates a wallet, and provisions an agent in the dashboard. Bots cannot create owner wallets or grant themselves credentials through MCP.

Start with `get_account_snapshot` and `list_markets`. Verify the credential's network and policy before proposing an order. Execution needs explicit user authorization for the trade or strategy. Keep credentials in the client's secret configuration, outside prompts and URLs.

Default execution: `place_order`, `cancel_order`, `set_leverage`, `transfer_collateral`, each with one durable requestId saved with its exact payload BEFORE calling. Preview is optional. Poll `get_operation(requestId)` or retry the SAME ID and parameters after timeout/unknown; never generate a new ID to recover ambiguity. Different parameters conflict. validForSeconds defaults to 30 (5–120), includes queue time, and retries never extend it. Request-ID bindings are not automatically pruned; never reuse IDs. not_found is scoped to this agent and the new API, not permission to create a fresh ID. Read statuses and actual fill sizes, not just HTTP success. `list_operations` recovers recent IDs. Nonces/signing remain internal. See /agent-guide.md for full schemas and retention details.

Optional `prepare_order` builds price/size strings from a fresh permitted market read: give market/side and size or notionalUsd, plus explicit limitPrice or slippageBps (default 50). It rounds size down and preserves explicit price boundaries. Returns a prepared order or blocked dust/minimum explanation; never auto-buys extra inventory. No preview/request ID, trade or reservation is created. It is not a balance/approval/liquidity check; place_order revalidates execution. Use only for new intents, never to alter an ambiguous retry's saved payload. REST: POST /api/v1/orders/prepare. Read /agent-guide.md for details.

Migration: use the new operation API for new intents. For an existing or ambiguous legacy preview/execute attempt, keep its original previewId and idempotencyKey and use the legacy retry/receipt path. Do not resubmit that intent as a new operation. Existing credentials and owner permissions are unchanged.

This file is documentation, not an authentication mechanism or an automatic connector installer. A cloud client needs a reachable HTTPS deployment. Localhost refers to the computer running the client.

## Agent integration

- [Agent connection guide](/agent-guide.md): Setup, MCP tools, REST fallback, retry rules, and a first handoff prompt.

## Optional

- [xAI remote MCP documentation](https://docs.x.ai/developers/tools/remote-mcp): Grok API configuration; separate from the Grok Bot app's connector installation.

Call get_account at startup, at least hourly, and before new risk; inspect access expiry and warnings. Final 24 hours of exchange access allow only perp reduce-only orders or inventory-backed spot sells. Use reconcile_order for uncertain receipts; never create a new key to retry an ambiguous order. Renewal requires the owner; no automatic position closure occurs.

Spot: explicit owner-approved USDC pairs use the same place_order tool (or optional preview/execute tools). Existing perps credentials do not gain spot access. Read the spot section of /agent-guide.md and list_markets; spot uses reduceOnly=false, available balances, and separate spot/perps account modes. Dynamic native/HIP-3/spot/HIP-4 discovery is available.

Owner permission updates: Agents → Edit permissions can add spot markets or change limits on an existing agent without replacing its token, signer or expiry. After a save, refresh get_account/list_markets. Unsubmitted previews are invalidated; keep original retry keys for submitted/ambiguous executions. Bots cannot edit policy themselves.

Live markets are discovered automatically across native perps, HIP-3 venues, spot and HIP-4 outcomes. New live agents default to all markets including future listings; existing selected grants need owner permission to expand. `list_markets` supports search, kind, dex, limit and offset; follow nextOffset. Read the dynamic-markets section of the agent guide before choosing collateral or identifiers.

Account management: new live agents created in the owner form/CLI default to leverage changes (maximum 100×, subject to each market’s exchange limit) and internal transfers ($100/action, $250/day), with adjustable permissions. Existing grants and explicit REST policies remain unchanged. Within your saved permissions, use get_collateral_routes / preview_collateral_transfer to move collateral within the same owner account, including perps with open positions up to withdrawable funds. Use get_perp_settings / preview_leverage_change to set cross or isolated leverage. Prefer the one-call transfer_collateral / set_leverage tools with a saved requestId. For the optional preview flow, both previews execute through execute_account_action; poll get_account_action and reuse original retry keys. Orders may require expectedLeverage {value,mode}; this verifies and does not set leverage. Unknown account actions pause execution and require owner review. Read the account-management section of /agent-guide.md.

Live orders support IOC/GTC/ALO and fixed-size reduce-only perp TP/SL triggers. Use get_open_orders, get_order and reconcile_order to inspect; cancel_order with orderRequestId cancels a managed bot order (receiptId targets legacy orders). Confirm terminal state and re-read positions before replacing. Native protection persists through service outages. Unknown outcomes never trigger automatic resubmission. See /agent-guide.md for schemas, recovery and unsupported API families.

HIP-4 catalog descriptions resolve exchange templates and parent-question rules. Inspect outcomeSpecification.status and question.specification, preserve exact #encoding order names, and read full rules before trading. Raw metadata remains available; unresolved templates are explicitly marked. Specification status is about template expansion, not market settlement.