Skip to main content
This page is the reference for the signing half of Self-custody trading: what each request asks the wallet to do, how to answer it, and what errors mean.

The request

Each entry in pendingSignatures[] 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.
Throwing from your signer is not a rejection. fillSelfCustody stops at once and drops the signatures it had collected for that batch, but the server has no reject call: the request simply expires and the fill fails. If you know a wallet cannot produce a raw-digest EIP-7702 authorization, fill with approveMode: "user_broadcast" instead.

Verifying a Hyperliquid action before signing

An hl_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.
The HyperCore fee transfers (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 carries expiresAt. 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
The wrap prompt is not one-time. Funding arrives as USDC.e, which must be wrapped before a buy settles, so a returning user sees it on every freshly funded buy.
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

Without fillSelfCustody, run this loop:
  1. POST /execution/fill with quoteId and signingAddress. The response never carries pendingSignatures, even for self-custody.
  2. Poll GET /execution/status?quoteId=, waiting pollAfterMs between calls.
  3. For each new pendingSignatures[] entry, have the wallet named by signerAddress sign or send the payload.
  4. Submit the results with the call below. Up to 32 entries. Send signature or txHash, not both. The response has the same shape as the fill response.
  5. Repeat from step 2 until terminal is true.
Submit signatures for a pending self-custody fill. Errors from the signatures endpoint: 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 same POST /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-712 ClobAuth 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 one cancel 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 }.
The API checks ownership, the exact asset and order, and the signer. An agent must still be approved when cancelling. A rejected request can be retried with a fresh signature. An order placed outside AGG through the user’s own agent, not the approved AGG agent, must be cancelled with a signature from the wallet itself. Only the wallet or its approved AGG agent is accepted. Open self-custody Hyperliquid orders are not cancelled by AGG. The client signs the cancellation. Native venue termination is still reconciled.