API Trading

Use this guide if you are integrating a market maker, quoting system, or execution service with Hypercall.

Production API

REST base URL: https://api.hypercall.xyz

WebSocket URL: wss://api.hypercall.xyz/ws

Testnet status: testnet is temporarily disabled until Hypercall acquires more testnet HYPE. New market maker integrations should use production unless Hypercall gives you a dedicated environment.

Allowlisted streams

Indicative quote-provider streaming is not generally available yet. Hypercall can enable it for approved integrations, but ordinary market maker onboarding should use REST market data plus authenticated order, fill, and portfolio WebSocket channels.

Onboarding Checklist

• Trading wallet: EVM wallet capable of signing EIP-712 typed data.
• Funding: production USDC funding at app.hypercall.xyz.
• Access: contact Hypercall if you need market maker limits, writer access, or indicative quote-provider streaming.
• Environment: production REST and WebSocket URLs above. Do not assume testnet is available.
• Reconciliation: persist your own client order IDs, nonces, orders, fills, and position snapshots.

Integration Paths

Rust Crates

Hypercall publishes public Rust crates for the supported integration surface:

The public Rust repository is github.com/hypercall-public/hypercall-rust.

Crate	Use
hypercall-client	REST client, WebSocket client, EIP-712 signing helpers, local signing, and AWS KMS signing
hypercall-sdk-types	Public request and response DTOs shared by the client
hypercall-ws-protocol	Public WebSocket message types
hypercall-hyperliquid	Optional Hyperliquid helper crate for integrations that also hedge on Hyperliquid
hypercall-liquidator	Standard Margin liquidation reference client. This is not required for normal market making

Use the crates when possible. They encode the current signing domain, request shapes, route rules, and string formatting rules that are easy to get wrong by hand.

Raw REST and WebSocket

If you are not using Rust, use the API Reference, Authentication & Signing, and WebSocket API pages as the source of truth.

1. Discover Markets

Start by loading the active markets and instrument specs:

curl https://api.hypercall.xyz/markets
curl "https://api.hypercall.xyz/instrument-specs?currency=BTC"
curl "https://api.hypercall.xyz/options-summary?currency=BTC"

Use:

• GET /markets for listed underlying and expiry groups.
• GET /instrument-specs?currency=BTC for tradable option specs.
• GET /options-summary?currency=BTC for chain-level best bid, best ask, mark, and Greeks-style summary fields.

2. Set Up Signing

Write operations use EIP-712 signatures.

• Production chain ID: 999
• Domain name: Hypercall
• Domain version: 1
• Verifying contract: 0x0000000000000000000000000000000000000000

Market makers should usually use an agent wallet:

1. Owner wallet approves an agent with POST /approve-agent.
2. Agent wallet signs orders and cancels for the owner wallet.
3. Owner wallet remains the portfolio, funding, and risk identity.

See Authentication & Signing for exact structs and field names.

3. Quote With Bulk Orders

For market maker quotes, use POST /bulk_order with route: "book_only".

curl -X POST https://api.hypercall.xyz/bulk_order \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "wallet": "0x...",
        "symbol": "BTC-20260131-100000-C",
        "price": "100.0",
        "size": "0.1",
        "side": "Buy",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-bid-1",
        "mmp_enabled": true,
        "nonce": 1001,
        "signature": "0x..."
      },
      {
        "wallet": "0x...",
        "symbol": "BTC-20260131-100000-C",
        "price": "101.0",
        "size": "0.1",
        "side": "Sell",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-ask-1",
        "mmp_enabled": true,
        "nonce": 1002,
        "signature": "0x..."
      }
    ]
  }'

Rules that matter:

• price and size are strings in both the signed payload and JSON body.
• String formatting must match exactly between the signature and JSON body.
• Bulk order size is capped at 50 orders per request.
• Bulk route is book-only. route: "best_execution" and route: "rfq_only" are single-order paths, not bulk quote paths.
• Most trading rejects return HTTP 200 with status: "REJECTED". Always inspect each result.

4. Refresh Quotes

Use PUT /bulk_order when you want to cancel existing quote orders and place replacements in one request.

curl -X PUT https://api.hypercall.xyz/bulk_order \
  -H "Content-Type: application/json" \
  -d '{
    "replacements": [
      {
        "wallet": "0x...",
        "order_id": 12345,
        "symbol": "BTC-20260131-100000-C",
        "price": "99.5",
        "size": "0.1",
        "side": "Buy",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-bid-1",
        "nonce": 1003,
        "signature": "0x..."
      }
    ]
  }'

PUT /bulk_order cancels the old batch before creating the new batch. Results are returned per replacement in request order. A failed cancel prevents that replacement order from being created.

For one latency-sensitive replacement, use PUT /order.

5. Subscribe to Updates

Connect to production WebSocket:

const ws = new WebSocket("wss://api.hypercall.xyz/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "Authenticate", wallet: "0xYourWallet" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "order_updates" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "fills" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "portfolio" }));
};

Use:

• order_updates for order status changes. Partial fill updates are intentionally omitted here.
• fills as the source of truth for partial fills and executed trades.
• portfolio for account state updates.
• orderbook, trades, options_chain, and index_prices for public market data.

See WebSocket API for channel formats and liveness behavior.

6. Reconcile State

Run a reconciliation loop even if your WebSocket connection is healthy.

State	REST fallback	WebSocket channel
Orders	GET /orders?wallet=...	order_updates
Fills	GET /fills?wallet=...	fills
Portfolio	GET /portfolio?wallet=...	portfolio
Markets	GET /markets, GET /instrument-specs	market_updates, options_chain

Recommended loop:

1. Load markets on startup.
2. Load open orders and latest fills before quoting.
3. Subscribe to WebSocket updates.
4. Quote with deterministic client IDs.
5. Poll REST periodically to recover from disconnects or missed messages.
6. Stop quoting on unknown state until REST and WebSocket state agree again.

7. Understand Launch Scope

Mainnet Alpha is intentionally constrained.

• Margin: Standard Margin is live. Portfolio Margin is not generally enabled.
• Writer access: short option exposure requires approved access.
• Indicative streaming: quote-provider streams are allowlisted and not a general public integration path yet.
• Liquidation tooling: the public liquidator crate is for Standard Margin liquidation workflows, not ordinary market making.
• Testnet: unavailable until Hypercall acquires more testnet HYPE.

Common Issues

Signature verification failed

• Check that price and size are JSON strings.
• Check that the signed strings exactly match the submitted strings.
• Use chain ID 999 for production.
• Use a fresh nonce for each signed write.
• Confirm the signer is the wallet or an approved agent.

Insufficient margin

• Check GET /portfolio?wallet=....
• Add collateral or reduce quote size.
• Confirm your wallet has the access level required for the strategy you are quoting.

Sell rejected for access or coverage

• Ensure the sell is covered by filled long inventory, or contact Hypercall for writer access.
• Do not assume writer access is enabled for a new wallet.

No fills on WebSocket

• Send an Authenticate message before subscribing to authenticated channels.
• Subscribe to fills, not only order_updates.
• Fall back to GET /fills?wallet=... after reconnecting.

Next Steps

• Authentication: Authentication & Signing
• WebSocket protocol: WebSocket API
• Rate limits: Rate Limits
• Errors: Errors & Rejection Reasons
• Reference: API Reference