Awaiting actions & polling - ILLA Documentation

Use these APIs when a tool execution continues asynchronously after submission.

Option 1: Await one action result

Use sdk.awaitAction when you want a single promise-based result tied to a chat.

const result = await sdk.awaitAction(chatId, {
  toolName: 'swap',
  protocol: 'lifi',
  args: { txHash: '0xabc...' },
})

if (result.isError) {
  console.error('Polling failed:', result.error)
} else {
  console.log('Status:', result.response.pollStatus)
}

Use sdk.subscribeToToolStatus for UI progress updates.

const subscription = sdk.subscribeToToolStatus(
  {
    toolName: 'bridge',
    protocol: 'lifi',
    descriptor: { txHash: '0xabc...' },
  },
  {
    onStatusChange: ({ previous, current }) => {
      console.log('prev:', previous?.pollStatus, 'curr:', current.pollStatus)
    },
    onError: (error) => {
      console.error('Polling error:', error)
    },
  },
  {
    interval: 5,
    retryThreshold: 30,
    maxRetries: 5,
    maxDuration: 600,
  },
)

// Later
subscription.unsubscribe()

Option 3: Use AsyncToolChecker directly

For lower-level control, use AsyncToolChecker.

import { AsyncToolChecker } from '@illalabs/sdk'

const checker = new AsyncToolChecker({ coreApiProvider: provider })

const once = await checker.check({
  toolName: 'defiWithdraw',
  protocol: 'aave',
  descriptor: { txHash: '0xabc...' },
})

Descriptor fields

toolName: action key (swap, bridge, defiSupply, defiWithdraw)
protocol: provider key (lifi, aave, …)
For awaitAction: args
For subscribeToToolStatus / AsyncToolChecker.check: descriptor

Polling config units

interval, retryThreshold, and maxDuration are seconds.