Skip to content
Temporal Docs← Back to the app

13 · Makers, agents & API

Makers, agents & API

Everything you can do on screen, your agent or your own program can do through the public routes. Your wallet signs every act; the agent never holds a venue key. Never paste a private key into a chat: the agent reads it from an environment variable.

This page has three parts: Makers (run your own quoting program or AI agent — the Custom way to earn), Agents (ready prompts for an AI agent, for traders and for makers) and API (the rule for every act, the routes, and the refusals).

Makers#

TLP is the default way to earn: one deposit, and the venue quotes and manages for you (the Earn tab, or temporal_maker_quoting with mode: "auto" and tlp: true). Custom is the port a maker's existing setup plugs into, and this section is for makers who bring their own pricing. Temporal does not run your strategy: it gives requests in, signed quotes out, and your account's state and acts for your own risk and margin systems. A Custom maker owns its pricing, its exposure limits, its stop rules and its margin; the venue enforces only its hard limits (Earn). The maker runs its own quoting program: for every order a trader sends, the venue asks every maker for a price on that exact option and size (it never says who is asking); each maker answers with a firm quote signed by its own key, and the single best quote fills the whole size at its own price (ties are drawn by room; the full rule is Matching). How fills reach you, the price limit, caps and closes: Earn.

The reference client

A runnable client for the port is in the agent kit (agent-kit/examples/custom-maker): it does the session, registration, the poll and answer loop, quote signing, the deadline, reading your account (equity, requirement, liquidation distance, positions) and the acts, and hands four seams to your own code: price(request) (your pricing surface), withinLimits(request, book) (your exposure limits), shouldQuote(state) (your stop rule: false stops answering and turns quoting off) and manageMargin(state, acts) (your top-up, withdraw and covering-perp choices, on a timer). All four are empty by default, so it quotes nothing until you connect your own system; money acts are dry runs unless you switch them live.

Set up and go live

  1. Fund and open your maker (EARN) account with signed ledger acts on POST /chain/intent (the same acts as every account: Wallet & accounts): connect and mintAccount with kind 3 (EARN) once, then deposit into it. Your exposure limits are what that money backs. GET /chain/state?wallet=<MY_WALLET> then lists the account and its number.
  2. Sign in with the wallet that owns it: POST /auth/nonce with your address, sign the message it returns, POST /auth/verify with address and signature. The answer is a session token; send it as Authorization: Bearer <token> on the routes below.
  3. Choose the market it quotes: POST /account/asset with { id, asset, primary: true } (id = the account, or null with ledgerAccountId = its number; only while it is not quoting and holds no position).
  4. Register your quoting program (next section), then go live: POST /account/quoting with { id, on: true, mode: "custom" } (or ledgerAccountId as above; mode: "auto" lets the venue quote it for you, as TLP does).
  5. Stop: POST /account/quoting with { id, on: false } takes your prices off; POST /rfq/maker/unregister with { id } disconnects the program.

Answer requests (the quoting program)

  • Register it: POST /rfq/maker/register with { transport, url, accounts, signer? }. transport is "webhook" (the venue POSTs each request to your url, which must be https://) or "poll" (no URL: you long-poll POST /rfq/maker/poll). accounts are the maker accounts you own; signer is optional: your bot key, if you set it as the account's quote signer on chain (setQuoteSigner). GET /rfq/makers lists your connections; POST /rfq/maker/unregister with { id } removes one.
  • A request is { id, asset, side, wing, strikeK, months, qty, deadlineMs }. side is the trader's side (0 = they buy, so you quote your ask). One option, one size per request — no ladders. It never names the trader.
  • Quote: reply within the window (about 500 ms) with { quote, sig }, or null to pass. The quote carries your account id as maker, taker 0, the request's asset, side, wing, strikeK and months, a qty of at least the size asked, priceUSD (USD with 6 decimals, per coin), an expiry at least 2 s ahead and a nonce you never reuse; it is signed as EIP-712 typed data Quote in the domain { name: "TemporalQuote", version: "1", chainId, verifyingContract } (the venue's front contract).
  • A Protect swap slice arrives as { kind: "package", legs: [...] }: answer every leg ({ quotes: [{ leg, quote, sig }, ...] }) or nothing.
  • The venue accepts a price only inside its price limit around the oracle venue's bid / ask, and only up to the room your limits leave. Field-by-field reference: Earn: register your quoting program.

A custom maker, step by step (example)

A maker with $5,000 who wants to quote BTC calls and puts from its own model:

  1. Sign connect, mintAccount (kind 3) and a $5,000 deposit on POST /chain/intent; GET /chain/state shows the new EARN account, say number 42.
  2. Sign in (/auth/nonce, /auth/verify), then POST /account/asset with { id: null, ledgerAccountId: 42, asset: "BTC", primary: true }.
  3. POST /rfq/maker/register with { transport: "poll", accounts: [42] }, then loop on POST /rfq/maker/poll, handing back your answers each time.
  4. POST /account/quoting with { id: null, ledgerAccountId: 42, on: true, mode: "custom" }. Requests now reach your program; each answer is priced by your model, inside the price limit, and signed.
  5. To stop: POST /account/quoting with on: false, then POST /rfq/maker/unregister.

Covering perp (opt in early)

A maker margins like Deribit / Derive: a buffer (BTC 15 / 10 / 7.5 %, HYPE 30 / 25 / 18 % of spot) plus the option's current price. Past what its money covers, a perp covers the excess (a long perp covers sold calls, a short perp sold puts); its margin is Hyperliquid's and comes out of the maker account, and its fees and funding are the maker's. Automatic (TLP) makers get one from the venue when needed. A Custom maker may ask for one earlier:

  • POST /account/makerPerp with { id, asset, side: "long" | "short" | "off", size } (size in coins; session; you must own the account). The size is capped at the coins you have sold on that side; one change per account per 15 minutes (else 429 too_soon with retryAfterMs); it is acted on at the venue's next pass. The answer is { ok, id, asset, side, size, requests, cover }. Refused by name before anything is stored: below_min (the size is under Hyperliquid's minimum order; the reply carries minSize) and deposit_short (your free deposit cannot fund the perp's margin; the reply carries needUSD and freeUSD).
  • GET /account/makerPerp?id=<ACCOUNT_ID> reads your asks and your covering perps. It also shows lastCancel: why your last covering perp was not placed, if one was not.
  • Your positions, read-only: GET /chain/state?wallet=<YOU> lists, on each of your EARN accounts, the options you wrote or bought against traders (legs, your side: sold if the trader bought, bought if the trader sold; asset, call or put, strike, months, size, entry price, the oracle price now, funding.paidUSD = the holding cost you received (+) or paid (−), openedAt) and your covering perps (perps: side, size, entry, mark, P/L, margin, Hyperliquid fee and funding). Each written row has an opaque id and says nothing about the trader. Closed ones: GET /activity?wallet=<YOU>&kind=earn rows t: "lpFill" with closes: true (instrument, entry and close price, your realised pnlUSD). The Portfolio (Earn section) shows them as read-only rows.

Positions and money

  • GET /chain/fills?wallet=<MY_WALLET>&account=<ACCOUNT_ID>: your fills. GET /chain/state?wallet=<MY_WALLET>: your accounts, positions, margin and room.
  • Take money out: a signed withdraw from the account on POST /chain/intent (up to what is withdrawable) moves it to your free cash; POST /chain/withdraw then sends free cash to HyperCore and GET /chain/withdrawals shows the queue.
  • Leave as a maker: the exitMaker act (built with POST /chain/build, signed like any act) hands the options you wrote to the other makers at market; it is refused by name (ExitOff) while the venue has exits switched off.
  • End the account: quoting off (POST /account/quoting with on: false), every position you hold closed (closeLegAtFront), the deposit withdrawn, then POST /account/close-all with { accountId }. A pending answer means "send it again shortly".

Agents#

What an agent needs

  • The base URL: https://protect.temporal.exchange/api/venue
  • A wallet it can sign with (from an environment variable), with USDC on Hyperliquid mainnet (real money, $100 per wallet during the beta). No gas coin needed.
  • A way to run the small scripts it writes for you (for example Node 22).

Connect an agent

Point an MCP-capable agent (Claude, Cursor and others) at https://protect.temporal.exchange/mcp (server card: /.well-known/mcp.json). It holds no key: the tools read, plan, build the ledger call (POST /chain/build), dry-run and prepare the typed data, and your wallet signs. The skills are temporal-protect (traders) and temporal-earn (makers).

Maker tools need a venue session: temporal_session_prepare returns the message, your wallet signs it, temporal_session_open returns a token that you pass on each maker call (the server keeps nothing and logs nothing). Then: temporal_maker_state (accounts, quoting, margin), temporal_maker_quoting (TLP is mode: "auto" with tlp: true), temporal_maker_settings and temporal_maker_asset (caps and spread, for TLP and AUTO accounts), temporal_maker_perp (covering perp), temporal_maker_rename, and for Custom temporal_maker_register, temporal_maker_connections and temporal_maker_unregister. Deposits, withdrawals, closes and exitMaker are temporal_build_call acts. Every maker write asks for confirmed: true after the person said yes, is never retried, and a refusal comes back by name.

Scripts

Any script your agent writes for you should work the same way: read, dry-run, show you the result, and stop until you confirm (for example, by running it again with CONFIRM=yes).

The ready prompt (traders)

You are my assistant for the Temporal perpetual-options venue (mainnet beta, real money). Read https://protect.temporal.exchange/docs/agents and follow it exactly. Check the venue is up, then show me my cash and accounts and wait for what I want to do. Use my wallet from the environment variable WALLET_KEY; never ask me for a key in chat.

The ready prompt (makers)

Paste this into your own AI agent. It plugs into the venue and runs quoting, positions and withdrawals through your wallet (wallet sign-in and wallet-signed acts); your keys are never shown or stored by the venue.

You are my market-making agent on Temporal. Temporal lists the same calls and puts as Deribit, made perpetual: no expiry and no time decay — the holder pays a small daily holding cost instead — plus protected perps (a perp with a built-in option hedge). I am a maker on its request-for-quote market: I run my own quoting program. For every order a trader sends, the venue asks every maker for a price on that exact option and size (it never says who is asking); each maker answers with a firm quote signed by its own key, and the single best quote fills the whole size at its own price.

API base URL: https://protect.temporal.exchange/api/venue
Authentication: use MY wallet. Sign in by signing the venue's login message with my wallet (POST /auth/nonce, sign it, POST /auth/verify) to get a session. Ask me to connect or sign; never ask for, print, log or share my private key or seed. You may sign quotes with a separate bot key only if I set it as my account's quote signer.

Default: if I only want to earn, use TLP (the venue quotes for me): after the deposit, POST /account/quoting with { id: null, ledgerAccountId, on: true, mode: "auto", tlp: true }. Do the rest of this prompt only if I bring my own pricing; then Custom is the port my own pricing, limits, stop rules and margin systems plug into, and the venue enforces only the price limit, margin and liquidation, open-interest caps and my room.

Read the market
- GET /chain/health: listed assets and venue status
- GET /chain/quote: what an option at a size would cost now (the oracle venue's bid / ask is the reference)
- GET /chain/state?wallet=<MY_WALLET>: my accounts, positions, margin and room

Set up
- Money moves only by acts my wallet signs, sent with POST /chain/intent (dry-run each with POST /chain/dryrun first): connect and mintAccount (kind 3, EARN) once, then deposit into my maker (earn) account; my exposure limits are what that money backs. GET /chain/state shows the account's number.
- POST /account/asset with { id, asset, primary: true } (or id null + ledgerAccountId): choose which market my maker account quotes (only while it is not quoting and holds no position)
- POST /account/quoting with { id, on: true, mode: "custom" } (or id null + ledgerAccountId): go live with MY program answering (mode "auto" would let the venue quote it for me); { id, on: false } stops

Answer requests (the quoting program)
- POST /rfq/maker/register with { transport, url, accounts, signer? }: transport "webhook" (url = the https address my program listens on) or "poll" (no url; long-poll POST /rfq/maker/poll), the maker account(s) I own, and optionally my bot key
- GET /rfq/makers lists my connections; POST /rfq/maker/unregister { id } removes one
- The venue sends my program each request: { id, asset, side, wing, strikeK, months, qty, deadlineMs }. side is the trader's side (0 = they buy, I sell at my ask). One option, one size per request — no ladders.
- Reply within the window (about 500 ms) with { quote, sig }, or null to pass. quote = { maker: my account id, taker: 0, the request's asset / side / wing / strikeK / months, qty (at least the size asked), priceUSD (USD with 6 decimals, per coin), expiry (at least 2 s ahead), nonce (never reused) }, signed as EIP-712 typed data "Quote" in domain { name "TemporalQuote", version "1", chainId, verifyingContract: the venue's front address }.
- A protected-perp request arrives as { kind: "package", legs: [...] }: answer every leg ({ quotes: [{ leg, quote, sig }, ...] }) or nothing.
- The venue only accepts a price inside its price limit around the oracle venue's bid / ask, and only up to the room my limits leave.

Positions and money
- GET /chain/fills?wallet=<MY_WALLET>&account=<ACCOUNT_ID>: my fills
- POST /account/makerPerp with { id, asset, side: "long" | "short" | "off", size } (size in coins): ask the venue for a covering perp early (long covers sold calls, short sold puts; capped at what I have sold on that side; one change per account per 15 minutes); GET /account/makerPerp?id=<ACCOUNT_ID> reads it
- Take money out: a signed withdraw from the account (POST /chain/intent, up to what is withdrawable) moves it to my free cash; POST /chain/withdraw, then GET /chain/withdrawals: send it to HyperCore and watch the queue
- End the account: quoting off, every held position closed (closeLegAtFront), the deposit withdrawn, then POST /account/close-all with { accountId } (a pending answer: send it again shortly)

Rules: quote only inside the exposure limits I give you. Check GET /chain/state before and after every change. Ask me before any withdrawal or close-all. Full reference: https://protect.temporal.exchange/docs/agents

API#

The rule for every act

Read → dry-run (POST /chain/dryrun) → tell the person what will happen and what it costs → wait for a yes → send. A refusal is a named reason and changes nothing: quote it, do not retry with other numbers unless asked.

How matching works (what the agent must tell the person)

  • An order (or each piece, default $1,000 of premium; set pieceUSD) is sent to every maker's quoting program; the single best firm quote that can take the whole size fills it; equal best prices are drawn at random, weighted by room (Matching).
  • NoSingleMaker(qty, maxRoom) means no single maker can take that size: offer maxRoom, or smaller pieces.
  • Slippage is measured from the oracle venue's side (ask for buys, bid for sells); the quote carries that reference.
  • Positions are valued at our venue: each leg and perp in chain/state carries valuation { oracleSide, venueAdj, value, marginValue, source, reason, at } (per coin) and each account valuation { valueUSD, plUSD, marginValueUSD, … }. value = the oracle closeable side adjusted to the best close quote for that size, used only inside the price limit and while fresh (else source: oracle-side); marginValue is never better than the oracle mid. closeMarkPerUnitUSD stays the plain oracle side. The ledger's own margin (margin.marked) still reads the oracle sides.

The reads (public, no key)

/health, /chain/health, /chain/quote, /chain/state, /chain/fills, /chain/deposits, /chain/withdrawals, /chain/nonce, /hypercore/balance, GET /access?wallet= (is this wallet invited, and how to ask), and the previews POST /perp/plan, POST /option/optimise, POST /chain/build (the venue builds the ledger call and its callHash from plain numbers), POST /chain/dryrun, POST /chain/snapshot, POST /earn/plan. Full list with parameters: `/llms.txt`.

The acts (signed)

POST /hypercore/relay (fund), POST /chain/intent (connect, mintAccount, deposit, withdraw, openLegAtFront, closeLegAtFront, closeAccountAtFront, openPerpWithLegs, requestClosePerp, exitMaker; EIP-712 VenueIntent), POST /chain/withdraw, POST /chain/withdraw/cancel. Makers: a session (/auth/nonce, /auth/verify, end it with /auth/logout), then /account/quoting, /account/makerPerp, /account/rename and the quoting-program routes under Makers. Every route and body is listed in `/llms.txt`.

When the venue says no

Common refusals: NoSingleMaker (size too big for any one maker — use pieces), NoMakerForOpen (nobody quotes that side), LegTooSmall (under $1 of premium), slippage over your limit, stale prices (asset frozen), margin short (the reply names both numbers), too_many_requests (this wallet has asked makers for many prices without trading on them: 60 unfilled requests in 10 minutes, 20 in any minute; the reply's retryAfterS says when it frees up; requests that filled and closes never count). Nothing moves on a refusal.

Then check the numbers

Verify it yourself turns the testing protocol into checks you can run on your own trades.

Kept in lockstep with the code: a check fails if this page drifts.

Everything above is also in one plain-text file for tools and AI agents: llms.txt. The venue's API is documented on Makers, agents & API, and Verify it yourself shows how to check any fill and mark against the chain.