Skip to main content

Prompt and Poll

Core patterns for sending prompts and receiving results.

Quick Method: promptAndWait​

The simplest way to use the SDK. Sends a prompt and waits for completion:

const result = await client.promptAndWait({
  prompt: 'what is the price of ETH?',
});

console.log(result.response);

Options​

const result = await client.promptAndWait({
  prompt: 'swap $10 of ETH to USDC',
  walletAddress: '0x...', // Optional: override context wallet
  interval: 2000,         // Optional: polling interval (ms)
  maxAttempts: 150,       // Optional: max poll attempts
  timeout: 300000,        // Optional: total timeout (ms)
});

Manual: Prompt Then Poll​

For more control, separate the prompt and polling:

Step 1: Submit Prompt​

const promptResponse = await client.prompt({
  prompt: 'buy $5 of BNKR on base',
});

console.log(promptResponse.jobId); // "abc123"
console.log(promptResponse.status); // "pending"

Step 2: Poll for Results​

const result = await client.pollJob({
  jobId: promptResponse.jobId,
  interval: 2000,    // Check every 2 seconds
  maxAttempts: 150,  // Max 150 attempts
  timeout: 300000,   // 5 minute timeout
});

if (result.status === 'completed') {
  console.log(result.response);
} else if (result.status === 'failed') {
  console.error(result.error);
}

Check Job Status (Single)​

Get status without polling:

const status = await client.getJobStatus('abc123');

console.log(status.status);      // "processing"
console.log(status.cancellable); // true

Cancel a Job​

Cancel a running job:

const result = await client.cancelJob('abc123');

console.log(result.status); // "cancelled"

Response Types​

JobStatus​

interface JobStatus {
  success: boolean;
  jobId: string;
  status: 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
  prompt: string;
  createdAt: string;
  processingTime?: number;
  response?: string;
  error?: string;
  transactions?: Transaction[];
  richData?: RichData[];
  cancellable?: boolean;
}

Handling Transactions​

The SDK returns transaction data that you must submit to the blockchain yourself. This is different from the Agent API, which executes transactions for you.

When a job returns transactions:

const result = await client.promptAndWait({
  prompt: 'swap $50 USDC to ETH on base',
});

if (result.transactions?.length) {
  for (const tx of result.transactions) {
    console.log(`Type: ${tx.type}`);
    console.log(`Chain: ${tx.metadata.chainId}`);
    console.log(`To: ${tx.metadata.transaction.to}`);

    // You must submit this transaction using your own wallet
    // Example with viem:
    // const hash = await walletClient.sendTransaction(tx.metadata.transaction);
  }
}
tip

If you don't want to manage transaction submission yourself, use the Agent API instead — it executes transactions automatically.

Handling Rich Data​

if (result.richData?.length) {
  for (const data of result.richData) {
    if (data.type === 'chart') {
      console.log(`Chart URL: ${data.url}`);
    } else if (data.type === 'social-card') {
      console.log(`Card: ${data.text}`);
    }
  }
}

Error Handling​

try {
  const result = await client.promptAndWait({
    prompt: 'invalid operation',
  });
} catch (error) {
  if (error.message.includes('Payment required')) {
    console.error('Insufficient USDC balance');
  } else if (error.message.includes('timeout')) {
    console.error('Operation timed out');
  } else {
    console.error('Unknown error:', error.message);
  }
}

XMTP Integration​

Format responses for XMTP messaging:

const result = await client.promptAndWait({
  prompt: 'swap $10 ETH to USDC',
  xmtp: true, // Formats transaction data for XMTP
});