Quick Start

Install the OptimAI tools, set an API key, and run a decentralized live web search request.

This quick start gets a developer from zero to one working request. The API examples use server-side code because API keys should not be shipped to a browser.

1. Set your API key

Create an API key at search.optimai.network/api-keys, then keep it outside source control.

export OPTIMAI_API_KEY="sk_live_..."

2. Run a copy-paste search

Use --fail-with-body so a non-2xx response still prints the API error body.

curl --fail-with-body https://api-onchain.optimai.network/external/v1/search \
  -H "X-API-Key: $OPTIMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quick-start-search-001" \
  -d '{
    "query": "What are the latest AI agent retrieval patterns?"
  }'

The API returns 202 Accepted with a search id. Poll the result until its status becomes terminal:

curl --fail-with-body \
  https://api-onchain.optimai.network/external/v1/search/SEARCH_ID \
  -H "X-API-Key: $OPTIMAI_API_KEY"

3. Call from TypeScript

const response = await fetch("https://api-onchain.optimai.network/external/v1/search", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.OPTIMAI_API_KEY ?? "",
    "Content-Type": "application/json",
    "Idempotency-Key": "quick-start-search-001",
  },
  body: JSON.stringify({
    query: "What changed in AI search infrastructure this week?",
  }),
})

if (!response.ok) {
  const message = await response.text()
  throw new Error(`OptimAI Search failed: ${response.status} ${message}`)
}

const created = await response.json()
console.log(`Search created: ${created.id} (${created.status})`)

Use GET /external/v1/search/:id to poll. A completed response stores the answer at result.answer and its evidence at result.citations.

4. Choose Search or Agent mode

Standard Search is the default and costs 1 credit. For longer multi-step web, social, and crypto research, explicitly send "search_mode": "agent"; Agent mode costs 2 credits and accepts text queries only.

5. Choose the right integration

Use case	Start here
A product backend needs live web answers	First Query
An AI coding agent should call OptimAI as a tool	Search MCP
A request should be paid through HTTP-native x402 flow	x402 SDK
A buyer needs escrow, verification, and onchain settlement	BNB Agent

6. Read the response

A completed Search response includes a cited answer under result.answer and source URLs under result.citations.

Next step

Continue with First Query for response handling patterns.