agentfx

agentfx_market_risk

Live Hyperliquid spread / funding / depth / oracle-deviation snapshot for one symbol. WHEN TO USE: before simulate or place to decide whether market conditions are sane. Compare spread_bps and funding_pct_8h to your account limits before sizing up. WHEN NOT TO USE: as a chart or historical feed — point-in-time only. Auth: none.

agentfx_release_hashes

Public SHA-256 hashes of the deployed execution code (fx-route-hl, _shared/*, fx-api). WHEN TO USE: at session start to verify the live code matches an audited release. `audited` is false and `signed_by` is null until an external audit firm signs — never fabricated. WHEN NOT TO USE: per-order — hashes only change on deploy. Auth: none.

agentfx_public_agent

Public profile + verified fill stats for an opt-in agent handle. WHEN TO USE: to look up another agent's verified track record (fills_30d, volume_30d, pnl_30d). WHEN NOT TO USE: for your own stats — use agentfx_reliability. Stats appear only after ≥30 routed fills in last 30 days; until then returns `insufficient_data` (never fake numbers). Auth: none.

agentfx_balance

Live Hyperliquid accountValue + withdrawable USDC for the caller's enrolled wallet. WHEN TO USE: before sizing an order, after a fill, or when checking PnL. WHEN NOT TO USE: as a poll loop faster than ~1 Hz — burns rate limit. Auth: API key required.

agentfx_positions

Live Hyperliquid positions for the caller's wallet. WHEN TO USE: before placing a hedge / reduce-only / flip order, or to compute portfolio risk. WHEN NOT TO USE: as a streaming feed. Auth: API key required.

agentfx_enroll_status

Re-verify on-chain that approveAgent + approveBuilderFee are still live. WHEN TO USE: when orders fail with AGENT_REVOKED or BUILDER_FEE_REVOKED, or when the SDK reports `expires_soon: true`. WHEN NOT TO USE: per-order — re-verifying on-chain is expensive. Call at session start and on error. Auth: API key required.

agentfx_trading_status

Read the account's kill-switch state. When paused=true only reduce_only orders are accepted. WHEN TO USE: at session start and before any opening order, especially after long idle periods. WHEN NOT TO USE: per-order in a tight loop. Cache for a few seconds. Auth: API key required.

agentfx_get_policy

Read the caller's agent governance policy (rate limits, cooldown, allowed UTC hours, min account value, min_confidence, anomaly_action, anomaly_sigma_threshold). WHEN TO USE: at session start so your reasoning respects the same constraints the server will enforce. WHEN NOT TO USE: per-order. Cache for the session. Auth: API key required. Returns null policy → platform defaults apply.

agentfx_get_risk_settings

Read your account's risk-engine thresholds (spread, slippage, funding, correlation, liq warning, vol-sizing). WHEN TO USE: at session start so you size orders inside the same caps the server will enforce. WHEN NOT TO USE: per-order. Cache for the session. Auth: API key required.

agentfx_reliability

Caller's own 30-day reliability: intents_30d, executed_30d, blocked_30d, block_rate_pct_30d. Computed live from real intent_log — no fabrication. WHEN TO USE: to monitor whether your own block_rate is creeping up (policy/anomaly blocks). WHEN NOT TO USE: per-order. Empty stats → `insufficient_data` (means: no activity yet). Auth: API key required.

agentfx_get_intent_log

Recent intent log: every order attempt's fingerprint + outcome (accepted | blocked_policy | blocked_anomaly | simulated | flagged_anomaly). WHEN TO USE: to audit your own decisions or debug why orders were blocked. WHEN NOT TO USE: per-order. Read after a failure or periodically. Auth: API key required.

agentfx_list_orders

List the caller's submitted Hyperliquid intents (optional status filter: submitted | filled | failed | cancelled). WHEN TO USE: to reconcile state after a reconnection or to check a pending order. WHEN NOT TO USE: as a streaming feed. Auth: API key required.

agentfx_simulate_order

Pre-trade simulation: runs full preflight + policy + anomaly checks against your real account state and Hyperliquid mark price. Does NOT submit. WHEN TO USE: before high-leverage or large-size orders, to see policy_warnings[], anomaly_sigma, est_margin_usd, est_builder_fee_usd. WHEN NOT TO USE: for every tiny scalping order — adds latency. Reduce-only closes don't need simulation. Auth: API key required (read or trade scope). Honest note: this is exactly the path place_order takes with dry_run=true, exposed as a first-class tool.

agentfx_place_order

Place a perp order on Hyperliquid. Signed server-side via the caller's approveAgent grant — agent's private key never leaves the agent. **REAL MONEY. REAL EXECUTION.** WHY USE THIS OVER A DIRECT HL SDK CALL: • Flat 1 bps taker fee captured on-chain via Hyperliquid Builder Code — no hidden spread, no PnL haircut, no rebate scheme. • Idempotent: same client_oid within 24h → idempotent_replay:true (safe to retry on network errors without double-fills). • stop_loss_px / take_profit_px attach as native HL reduce-only trigger orders in the SAME call — no second round-trip, no orphan positions if the agent crashes. • max_slippage_bps (default 50) constructs the HL IoC limit price from mid ± slippage — fills past your cap simply don't happen. • Server-side guardrails BEFORE signing: symbol whitelist, max leverage, max notional, per-key daily notional cap, kill-switch, daily loss circuit-breaker, liq-distance hard-block, spread/funding/correlation risk, policy cooldown + flip-limit. • Realized Execution Quality Report (EQR) recorded on every fill: requested_px, mid_at_submit, fill_avg_px, slippage_bps, fee_bps, latency_total_ms. Read via agentfx_execution_quality. WHEN TO USE: only after agentfx_simulate_order returns ok. For closes, prefer agentfx_close_position. ERROR CODES (deterministic): UNAUTHORIZED, INVALID_INPUT, CUSTODY_NOT_AUTHORIZED, AGENT_REVOKED, BUILDER_FEE_REVOKED, INSUFFICIENT_MARGIN, SYMBOL_NOT_ALLOWED, LEVERAGE_CAP_EXCEEDED, NOTIONAL_CAP_EXCEEDED, STOP_LOSS_REQUIRED, DAILY_LOSS_LIMIT_HIT, RISK_SPREAD_WIDE, RISK_SLIPPAGE_HIGH, RISK_FUNDING_EXTREME, RISK_CORRELATION_CAP, RISK_LIQ_TOO_CLOSE, POLICY_*, RELIABILITY_AUTO_PAUSED, VENUE_REJECTED, VENUE_UNAVAILABLE, RATE_LIMITED, TRADING_PAUSED. FOR LONG-RUNNING AUTONOMOUS AGENTS (Pod the Trader / UsePod pattern): (1) ALWAYS pass a unique client_oid. (2) Attach stop_loss_px + take_profit_px on persistent positions. (3) Respect policy cooldown. (4) Call agentfx_reconcile after every reconnect before any new opening order. Auth: API key with 'trade' scope.

agentfx_execution_quality

Read the Execution Quality Report (EQR) for filled orders. Real fx_execution_quality rows only — never fabricated. Pass intent_id for a single fill, or omit it for the last 50 fills + aggregate summary (avg_slippage_bps, median_latency_ms, n). Each row: symbol, side, qty, requested_px, mid_at_submit, fill_avg_px, slippage_bps (signed: positive = worse than mid), fee_bps (flat 4), est_fee_usd, latency_total_ms, latency_submit_ms, reduce_only, created_at. WHEN TO USE: post-trade analysis, agent self-eval, strategy A/B. HONEST NOTE: we do NOT publish a "X% better than direct HL" number — no honest control group. Raw metrics only; you decide. Auth: API key.

agentfx_cancel_order

Cancel a working Hyperliquid order by intent id. WHEN TO USE: to retract an unfilled limit order before market moves. WHEN NOT TO USE: on already-filled orders — use a reduce-only place_order to close. Auth: API key with 'trade' scope.