Skip to main content

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.

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

npm install @illalabs/sdk

​
2. Create the client

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

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

// 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

​
Use lower-level components if needed

If you need custom transport or custom context persistence, you can use the lower-level components directly: 
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 for the lower-level surface.