> ## 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.

# Types and utilities

> Key public contracts used when integrating with the SDK

This page documents high-value types used across the ILLA SDK, `Chat`, and polling APIs.

## Core request/response types

### `ChatOptions`

```ts theme={null}
type ChatOptions = {
  id?: string
  coreApiProvider: ICoreApiProvider
  contextManager: IContextManager
  defaultRole?: PromptRole
  modelContext?: ModelContext
  userContext: UserContext
  asyncToolChecker?: AsyncToolChecker
  personalityContext?: PersonalityContext
}
```

### `SendMessageOptions`

```ts theme={null}
type SendMessageOptions = {
  signal?: AbortSignal
  onRequestId?: (requestId: string) => void
}
```

### `SendMessageStreamingOptions`

```ts theme={null}
type SendMessageStreamingOptions = {
  signal?: AbortSignal
  onEvent?: (event: TelemetryEvent) => void
  onTextDelta?: (delta: string) => void
  onComplete?: (result: ValidatedResultEventData) => void
  onError?: (error: Error) => void
}
```

### `SendMessageResult`

```ts theme={null}
type SendMessageResult = {
  chatId: string
  requestId?: string
  prompt: CoreApiChatBodyRequest['prompt']
  promptSnapshot: PromptSnapshot | PromptSnapshot[]
  messages: MessageHistoryType
  toolsConfig: ToolAutorouterRequest
  response:
    | { isError: false; data: CoreApiChatSuccessResponse }
    | { isError: true; error: CoreApiChatErrorResponse }
}
```

## Context and persistence

### `IContextManager`

Key methods:

* `getContext(chatId)`
* `setMessages(chatId, messages)`
* `appendMessages(chatId, messages)`
* `setToolsConfig(chatId, toolsConfig)`
* `clearContext(chatId)`
* `deleteContext(chatId)`

### `ChatContextSnapshot`

```ts theme={null}
type ChatContextSnapshot = {
  messages: MessageHistoryType
  toolsConfig: ToolAutorouterRequest
}
```

## Polling and async action types

### `AsyncToolCheckerCheckParams`

```ts theme={null}
type AsyncToolCheckerCheckParams = {
  toolName: string
  protocol: string
  descriptor: BaseLongPollingArgs
}
```

### `AwaitableActionDescriptor`

Alias used by `awaitAction`:

```ts theme={null}
type AwaitableActionDescriptor = {
  toolName: string
  protocol: string
  args: BaseLongPollingArgs
}
```

### `PollingConfig`

```ts theme={null}
type PollingConfig = {
  interval: number
  maxDuration: number
  retryThreshold: number
  maxRetries: number
}
```

All polling values are seconds.

### `EventSubscription`

```ts theme={null}
type EventSubscription = { unsubscribe(): void }
```

## Pending tool payload

`PendingToolCallType` includes optional simulation metadata and multiple executable input shapes:

```ts theme={null}
type PendingToolCallType = {
  type: 'tool-call'
  toolCallId: string
  toolName: string
  input:
    | { type: 'SingleTransaction'; value: TransactionWithMetadata }
    | { type: 'BatchTransactions'; value: TransactionWithMetadata[] }
    | { type: 'SignatureRequests'; value: { signatureRequests: SignatureRequest[] } }
    | { type: 'ActionSequence'; value: ActionStep[] }
  simulated?: boolean
  simulation?: SimulationResult
}
```

### `ActionSequence`

An ordered array of steps that must be executed sequentially. Each step can be a `SingleTransaction`, `BatchTransactions`, or `SignatureRequests`.

```ts theme={null}
{
  type: 'ActionSequence',
  value: [
    { type: 'BatchTransactions', value: [{ transaction: usdcTransfer }] },
    { type: 'SignatureRequests', value: { signatureRequests: [orderSignature] } },
  ],
}
```

### `SignatureRequest`

Discriminated union based on `signMethod`:

```ts theme={null}
type SignatureRequest =
  | {
      signMethod: 'typedData'
      id: string
      signerAddress: string
      description?: string
      metadata?: Record<string, unknown>
      typedData: EIP712TypedData
    }
  | {
      signMethod: 'message'
      id: string
      signerAddress: string
      description?: string
      metadata?: Record<string, unknown>
      rawHash: string
    }
```

## Simulation types

When simulation is enabled server-side, pending tools may include a `SimulationResult` describing the expected transaction outcome.

### `SimulationResult`

```ts theme={null}
type SimulationResult = {
  willSucceed: boolean
  assetChanges: AssetChange[]
  gasEstimate: GasEstimate
  errorMessage?: string
  errorExplanation?: string
  simulationId?: string
  simulatedAt: number
  actionType?: SimulationActionType
  sourceChainId?: number
  destChainId?: number
  actionMetadata?: ActionMetadata
  contractInteractions?: ContractInteraction[]
  nativeTokenSymbol?: string
}
```

### `AssetChange`

```ts theme={null}
type AssetChange = {
  tokenAddress: string
  tokenSymbol: string
  tokenName: string
  decimals: number
  rawAmount: string
  formattedAmount: string
  usdValue: string
  direction: 'in' | 'out'
  logoUrl?: string
}
```

### `GasEstimate`

```ts theme={null}
type GasEstimate = {
  gasLimit: string
  gasPrice: string
  gasCostNative: string
  gasCostUsd: string
}
```

### `SimulationActionType`

```ts theme={null}
type SimulationActionType =
  | 'transfer'
  | 'swap'
  | 'bridge'
  | 'supply'
  | 'withdraw'
  | 'contract'
```

### `ActionMetadata`

```ts theme={null}
type ActionMetadata = {
  inputToken?: string
  inputAmount?: string
  inputUsdValue?: string
  outputToken?: string
  outputAmount?: string
  outputUsdValue?: string
  chainName?: string
  destChainName?: string
  protocol?: string
  recipient?: string
}
```

### `ContractInteraction`

```ts theme={null}
type ContractInteraction = {
  address: string
  name?: string | null
  method?: string | null
  chainId: number
}
```

## Narrowing result safely

```ts theme={null}
const result = await sdk.sendMessage('Hello', { userContext: { address: '0x1234...' } })

if (result.response.isError) {
  console.error(result.response.error.name, result.response.error.message)
} else {
  console.log(result.response.data.text)
  console.log(result.response.data.pendingTools)
}
```

## See also

* [Errors](/sdk/api/errors)
* [Streaming events](/sdk/api/streaming-events)