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

# Quickstart

> Build your first chat flow with the ILLA SDK

This guide shows the shortest path to a working ILLA integration with `IllaSDK`.

By the end, you will be able to:

* initialize the SDK
* send a user message
* inspect `pendingTools`
* continue the same chat

## Before you start

* Node.js 20+
* An ILLA API key
* A wallet address for `userContext.address`

## 1. Install

```bash theme={null}
npm install @illalabs/sdk
```

## 2. Create the client

```ts theme={null}
import { IllaSDK } from '@illalabs/sdk'

const sdk = new IllaSDK({
  apiKey: process.env.ILLA_API_KEY!
})
```

`IllaSDK` is stateful. It creates chats, remembers active chat IDs, and exposes helpers for tool execution and polling.

## 3. Send the first message

```ts theme={null}
const result = await sdk.sendMessage(
  'What can I do on Base today?',
  {
    userContext: {
      address: '0xYourAddress',
      // Optional: EOA signer for smart-account flows
      // signerWallet: '0xYourSignerAddress'
    }
  }
)

if (!result.response.isError) {
  console.log('Assistant:', result.response.data.text)
  console.log('Chat ID:', result.chatId) // Save this to continue the conversation

  // Check if there are pending tools to execute
  if (result.response.data.pendingTools) {
    console.log('Pending tools:', result.response.data.pendingTools)
  }
} else {
  console.error('Error:', result.response.error)
}
```

If the assistant returns `pendingTools`, your app is expected to execute those actions and send the outcomes back with `sendToolResults`.

## 4. Continue the same chat

```ts theme={null}
// Use the chatId from the previous message to continue
const followUp = await sdk.sendMessage(
  'Swap 1 ETH for USDC',
  { chatId: result.chatId }
)

if (!followUp.response.isError) {
  console.log('Assistant:', followUp.response.data.text)
}
```

## What to do next

* Handle tool execution: [Handling tool execution](/sdk/guides/handling-tool-execution)
* Build a complete flow: [Building a chat flow](/sdk/guides/building-a-chat-flow)
* Handle errors properly: [Error handling](/sdk/concepts/error-handling)

## Use lower-level components if needed

If you need custom transport or custom context persistence, you can use the lower-level components directly:

```ts theme={null}
import {
  Chat,
  ContextManager,
  CoreApiProvider,
  InMemoryCache,
  Prompt,
} from '@illalabs/sdk'

const provider = new CoreApiProvider({
  headers: { 'x-api-key': process.env.ILLA_API_KEY! },
})

const context = new ContextManager(new InMemoryCache())

const chat = new Chat({
  coreApiProvider: provider,
  contextManager: context,
  userContext: {
    address: '0xYourAddress',
    // Optional signer EOA for smart-account + signature flows
    // signerWallet: '0xYourSignerAddress'
  },
})

const prompt = new Prompt({ text: 'What can I do on Base today?' })
const res = await chat.sendMessage(prompt)

if (!res.response.isError) {
  console.log('Assistant:', res.response.data.text)
}
```

See the [Chat API reference](/sdk/api/chat) for the lower-level surface.