Skip to main content
When ILLA needs your application to execute an on-chain action, the response includes pendingTools. Your app becomes the executor: run those tools, collect the result, and send the outcome back with sendToolResults.

What this guide covers

  • how to read pendingTools
  • how to run the standard execution loop
  • how to handle ActionSequence and signature requests
  • how to use simulation previews safely
  • when to use polling helpers

Read pendingTools

Each item in pendingTools includes:
  • toolCallId
  • toolName
  • input
  • simulated (optional)
  • simulation (optional simulation preview payload)
input.type can be:
  • SingleTransaction
  • BatchTransactions
  • SignatureRequests
  • ActionSequence
tool.input is always the execution source of truth. Optional simulation fields are for display and review.

Run the standard execution loop

Use batched outcome submission (sendToolResults) and continue until no more tools are returned.
This is the default pattern for SDK integrations.

Handle ActionSequence

When input.type is ActionSequence, the value is an ordered array of steps. Execute steps sequentially and preserve the server-defined order.
A common pattern is a prediction-market flow that transfers funds first and collects a signature second.

Handle signature requests

Some tools return SignatureRequests directly, or as a step inside ActionSequence. Signature requests use either EIP-712 typed data (signMethod: 'typedData') or raw hash signing (signMethod: 'message'). Your executor should collect signatures and return them in the tool result payload, then continue the loop normally. Common flows include:
  • predictionMarketsBet
  • predictionMarketsRedeem
  • polymarketPostOrder
  • polymarketPostRedeem

Use simulation previews for review UI

When simulation is enabled server-side, pending tools may include a simulation object that you can use to build a confirmation UI before execution.
Key fields worth surfacing:
  • willSucceed
  • assetChanges
  • gasEstimate
  • actionType
  • contractInteractions
  • actionMetadata
Treat simulation as display-only metadata. tool.input remains the execution source of truth.

End-to-end example

Track long-running tools

For tools that may take longer after submission (for example bridge completion), use polling helpers with the transaction hash:

Common mistakes

  1. Ignoring failed tools instead of returning an error outcome.
  2. Executing ActionSequence steps out of order.
  3. Using simulation output as the execution payload.
  4. Sending many single tool results when one batched call would work.