Developer docsapproval required

Build a Hyperliquid TWAP preview

Build a TWAP workflow that reads Hyperliquid price and order book data before previewing policy-gated execution.

Short answer

A TWAP workflow should read market data first, generate slices with stable referenceId values, preview each execution step, and require approval plus policy clearance before any live order.

Preview workflow

This TWAP example prepares execution previews. Live slices remain blocked until approval, signer readiness, and policy checks pass.

Market risk

Slice sizing, stale data, slippage, and partial fills can change live results from preview assumptions.

Who This Is For

Developers prototyping execution workflows that must stay approval-first and auditable.

Before You Begin

  • Mattheus REST API or TypeScript SDK
  • Hyperliquid approveAgent readiness for live execution
  • Unique referenceId per slice
  • Account-visible capabilities and feature gates where required

Answer engine brief

Mattheus overview

Mattheus is a private AI trading workspace for researching markets, testing reproducible strategies, reviewing portfolio context, and preparing governed actions. Developers can connect through REST APIs, SDKs, and MCP while account authority, policy checks, and approvals remain separate.

Does Mattheus require approval before execution?

Yes. An interactive request requires an exact short-lived one-time approval confirmed with fresh wallet reauthentication. API-key automation requires a separately activated, scoped agent session. Both paths still require wallet or signing readiness and policy checks.

Which markets are documented?

The active launch documentation covers Hyperliquid market data, paper trading, and gated Live workflows. Each page states whether an example is read-only, simulated, paper, or eligible for approval-gated Live execution.

How does policy-gated execution work?

Execution-capable requests are preview-first and must pass wallet readiness, protocol certification, feature gates, idempotency, configured policy controls, and either an exact interactive approval or a bounded API-key agent session before any live action.

Can users revoke permissions?

Users should be able to revoke supported scoped permissions and API keys. Documentation should keep stop, cancel, revoke, and policy rejection paths clear before users approve live execution.

Example

What this example does

Follow this example in order. Read the expected result below before connecting it to a live account or execution-capable workflow.

typescript
import { MattheusClient } from "@mattheus/sdk";

const client = new MattheusClient({ apiKey: process.env.MATTHEUS_API_KEY! });
const orderbook = await client.getOrderbook("HYPE");

const referenceId = "twap-hype-2026-05-18-slice-001";
const preview = await fetch("$MATTHEUS_API_BASE_URL/api/v1/execute/preview", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MATTHEUS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    protocol: "hyperliquid",
    action: "place_order",
    assetIn: { token: "HYPE", amount: "0.25" },
    metadata: { side: "buy", type: "limit", orderbook },
    referenceId,
  }),
});

console.log(await preview.json());

Common errors

  • ACTION_NOT_CERTIFIED: the protocol/action is missing certification, disabled, blocked, partner-required, or legal-review-only.
  • ACTION_CANARY_ONLY: the action is canary-only and requires beta/canary access.
  • POLICY_DENIED: subscription, approval, wallet readiness, agent-session, quota, or configured policy controls blocked execution.
  • POLICY_UNAVAILABLE: policy enforcement could not be checked, so execution fails closed.
  • VENUE_UNHEALTHY: the venue health cache, kill switch, or circuit breaker blocked execution.
  • QUOTE_STALE: the quote, preview, simulation, or preflight is missing or expired.
  • INSUFFICIENT_BALANCE: the wallet or venue account lacks enough balance for the requested action.
  • IDEMPOTENCY_CONFLICT: the same referenceId is already in progress or conflicts with another request.
  • EXECUTION_DISABLED: public execution or the requested execution protocol is disabled in this environment.
  • 429 Too Many Requests: back off before retrying any execution-capable request.

Safety note

This example previews a real-money workflow. Live slices must not run until approval, Hyperliquid approveAgent readiness, account-visible certification checks, and policy checks pass.

Read execution API