> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Awaiting actions & polling

> Track long-running blockchain actions triggered by tool execution

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.

```ts theme={null}
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)
}
```

## Option 2: Subscribe to status transitions

Use `sdk.subscribeToToolStatus` for UI progress updates.

```ts theme={null}
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`.

```ts theme={null}
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**.