The request
Each entry inpendingSignatures[] looks like this:
What each type asks for
Send exactly one of
signature and txHash per step. Signatures are 0x-prefixed hex.
A fill funded entirely from a legacy Polymarket Safe asks for one safe_tx signature and never an
approve or an EIP-7702 authorization. A fill funded from a Safe plus another wallet on the same
chain also asks for the usual steps for that other wallet.
A complete signer
fillSelfCustody calls your signer once per request. Return a hex signature, or { txHash } for a
transaction.
Verifying a Hyperliquid action before signing
Anhl_l1_action payload only carries connectionId, a hash of the action. To check what you
sign, recompute it from req.hlAction:
No vault and no
expiresAfter are used, so the hash ends in a single 0x00 vault byte.
eip712, purpose: "app_fee") are plain SendAsset typed data, so
their destination and amount are readable in payload.message directly.
When transaction reaches the trader. In two cases. On a bridge: the source token needs an
on-chain approve rather than a permit signature, and the fill set
approveMode: "user_broadcast". Omitting approveMode, or sending approveMode: "sponsored", asks for that same approval as eip7702_authorization: a raw digest, not EIP-712 and not EIP-191. A permit stays eip712. That split matches Choosing an approve mode.
Choosing the mode in PlaceOrder. A signer may implement the optional
canSignEip7702Authorization(address). PlaceOrder sends approveMode: "sponsored" only when it
returns true for the signing address and, on a buy, for every funding wallet, because the
authorization is signed by the wallet that pays for the bridge. It sends approveMode: "user_broadcast"
otherwise, including when the method is absent. The bundled wagmi signer does not implement it (viem cannot sign an
authorization for a JSON-RPC wallet), so it fills with user_broadcast.
On a Limitless, Predict or Myriad fill: the venue’s own approvals (see
Venues) are always sent by the wallet, whatever the approve mode,
and always arrive before the order signature. Venue orders, the Polymarket wrap, and the
Hyperliquid builder-fee approval are always signatures.
The other transaction you may see is an app-paid referral payout addressed to your payer wallet.
Check signerAddress before you prompt. See Fees.
After a transaction, return the hash without waiting. AGG watches for the mined receipt and does
not continue until it matches the request.
Timeouts, and what expiry means
Every request carriesexpiresAt. Read it; never hard-code a deadline. Steps in one fill can
have different deadlines, and the shortest is tight:
When a fill dies,
GET /execution/status reports overallState failed or expired with an
errorReason, and fillSelfCustody throws with that state in its message.
An expired request disappears from the pending list rather than showing as expired, so an empty list
never means “done”. Only terminal: true does. Submitting a signature for an expired request
returns 400. There is no recovery: quote again. A user has one live execution at a time. If a
request expires instead of being answered, a new fill does not start until the abandoned one has
finished failing, so ask the user to complete or abandon deliberately.
How many wallet prompts the user sees
Requests parked together arrive in one batch, but the user approves each one. The total is the sum of three parts: the venue order, a Polymarket funding step, and the funding transfers. Venue order
Polymarket funding step
In the rows below, “default mode” means
approveMode omitted or approveMode: "sponsored": the extra approval is eip7702_authorization, not EIP-712. user_broadcast is approveMode: "user_broadcast".
Funding transfers, per funding source. A route funded from two chains pays this twice.
In the default mode, with a partner fee on an EVM-funded buy, the funding batch also carries the fee transfers. A
user-paid referral is one more transfer in the same batch.
Worked examples: a Hyperliquid buy from an existing Hyperliquid balance is 1 prompt (2 while the
builder approval is outstanding). A Polymarket buy bridged from native USDC is 4 (one funding
transfer, one wrap, two order signatures), and stays 4 on repeat. The same buy from a token needing
an approval, before the first authorization, is 6. A Polymarket sell is 2, or 3 the
first time that deposit wallet trades.
Withdrawals, per source. A withdrawal never asks for a
transaction. Details and the sources
each mode allows are on Self-custody withdrawals.
Driving the loop yourself
WithoutfillSelfCustody, run this loop:
POST /execution/fillwithquoteIdandsigningAddress. The response never carriespendingSignatures, even for self-custody.- Poll
GET /execution/status?quoteId=, waitingpollAfterMsbetween calls. - For each new
pendingSignatures[]entry, have the wallet named bysignerAddresssign or send the payload. - Submit the results with the call below. Up to 32 entries. Send
signatureortxHash, not both. The response has the same shape as the fill response. - Repeat from step 2 until
terminalistrue.
Resubmitting a step that already succeeded is ignored, so retrying a batch after a network error is
safe. Do not send the same
stepId twice in one body: duplicates collapse to the last entry, so one
bad entry discards the good one and the request fails.
purpose: "hl_referral" with optional: true is the one-time Hyperliquid referral on the user’s account. If the signer skips it or it expires, submit the rest. The trade still proceeds. See Builder codes.
Limit-order cancel signatures
Managed cancel without a signature is on Limit orders. A self-custody cancel is the samePOST /execution/orders/cancel, plus cancelSignature. Cancel an order.
AGG does not store the Polymarket L2 credentials it derives from a cancel, and it never starts or retries a self-custody cancel on its own. A stale read after you submit returns cancel_pending. Keep polling until the order is cancelled, or filled / partial_fill if a fill won the race.
Polymarket
Sign Polymarket’s EIP-712ClobAuth with the order’s signing wallet. Domain { name: "ClobAuthDomain", version: "1", chainId: 137 }. Primary type ClobAuth with address (address), timestamp (string), nonce (uint256), and message (string). address is the signing wallet. timestamp is the current Unix time in seconds, as a decimal string. nonce is 0. message is This message attests that I control the given wallet.
signerAddress must be linked to the signed-in user and must be the wallet that produced cancelSignature. An address that is not linked returns 400. AGG reads the venue order first. If it is not open and owned by that wallet, the call returns 409. That covers not found, already filled, already cancelled, and not yours. A success can still come back with an empty orderIds when the venue cancelled the order and AGG could not record it. The cancel on the venue still happened. Fills that happened before the cancel are not recorded. This does not work for a polymarket.com email or Magic wallet: that flow trades from a different wallet than the one linked here. If venueOrderId is an order AGG placed, it is cancelled the same way as cancelManagedOrder.
Hyperliquid
Build onecancel action with the venue’s numeric asset id and the order’s venueOrderId. Sign it with the EOA or its currently approved agg agent. Use a fresh millisecond nonce. The signature is { r, s, v }.