Logo
Documentation Menu
AIR SDK

Quickstart

Go from zero to your first smart page interaction in under 2 minutes.

1

Install

Install the AIR SDK. Requires Node.js 18+. Works with Playwright, Puppeteer, or Browser Use.

Terminal
npm install @arcede/air-sdk
2

Get your API key

Run the interactive setup to generate your API key. It's saved to ~/.config/air/credentials.json with secure permissions, and optionally to .env for Playwright/Puppeteer usage.

Terminal
npx @arcede/air-sdk init

Or get one from the dashboard. Your Platform API key works across all AIR products.

Free tier includes 100 requests/month with no credit card required.

3

Wrap your page

Call withAIR on any Playwright page. Your agent gets resilient selectors, site awareness, and capability caching with two lines of code.

with-air.ts
import { chromium } from 'playwright';
import { withAIR } from '@arcede/air-sdk/playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
const smartPage = withAIR(page, { apiKey: process.env.AIR_API_KEY });

await smartPage.goto('https://news.example.com');
await smartPage.fill('input[name="search"]', 'AI agents');
await smartPage.press('input[name="search"]', 'Enter');

console.log(await smartPage.title());
await smartPage.destroy();
await browser.close();
4

See what's possible

Use the SDK to discover what actions a site supports. The SDK reads agent.json policies and caches capabilities automatically.

capabilities.ts
const caps = await smartPage.air.listCapabilities('news.example.com');
console.log(caps);
Response
[
  {
    "name": "search_articles",
    "description": "Search articles by keyword, topic, or date range.",
    "parameters": [
      { "name": "query", "type": "string", "required": true },
      { "name": "topic", "type": "string", "required": false },
      { "name": "from", "type": "date", "required": false }
    ],
    "actionType": "search",
    "confidence": 0.92,
    "macroAvailable": true,
    "source": "verified"
  },
  {
    "name": "get_trending",
    "description": "Get trending stories for a given category.",
    "parameters": [
      { "name": "category", "type": "string", "required": true },
      { "name": "limit", "type": "number", "required": false }
    ],
    "actionType": "api",
    "confidence": 0.87,
    "macroAvailable": false,
    "source": "community"
  }
]
5

Agent Skill Setup

Give your AI coding agent four web tools with one command. Supports Claude Desktop, Claude Code, Cursor, Windsurf, and OpenClaw.

Recommended
Terminal
# Recommended — one command setup
npx @arcede/air-sdk install-skill

# Auto-detects Claude Desktop, Claude Code, Cursor, Windsurf, and OpenClaw
# Writes MCP config and injects your API key

Alternative: Manual Setup

Claude Code CLI
# Or add via Claude Code CLI:
claude mcp add air-sdk -e AIR_API_KEY=your_key_here -- air-sdk --mcp
Or add JSON config manually...
mcp.json
// Recommended: use global binary (npm install -g @arcede/air-sdk)
{
  "mcpServers": {
    "air-sdk": {
      "command": "air-sdk",
      "args": ["--mcp"],
      "env": {
        "AIR_API_KEY": "your-api-key-here"
      }
    }
  }
}
// If not installed globally, use "command": "npx" with "args": ["-y", "@arcede/air-sdk", "--mcp"]

Performance Tip

The MCP server starts ~60s with npx due to package resolution. For instant startup (~2s), install globally:

Terminal
# Install globally for fast startup (~2s vs ~60s with npx)
npm install -g @arcede/air-sdk

# Then run install-skill to auto-configure all detected agents
npx @arcede/air-sdk install-skill

# install-skill writes the absolute binary path (e.g. /opt/homebrew/bin/air-sdk)
# to each agent config, avoiding npx version caching issues on upgrades.

Tools Your Agent Gets

  • extract_urlExtract structured data from any URL
  • browse_capabilitiesDiscover what actions can be automated on a website
  • execute_capabilityGet a structured execution plan with CSS selectors and fallbacks
  • report_outcomeReport results to improve the collective intelligence
6

Pay Per Request (No Account Needed)

All AIR APIs support x402 micropayments. Your agent pays per-request with USDC on Base — no API key or account required. When your agent calls an endpoint without authentication, it receives a 402 challenge that x402-compatible agents resolve automatically.

AIR SDK: $0.002 / macro execution

Terminal
# Agents can execute macros without an account using x402 micropayments ($0.002/execution).
# The API returns a 402 challenge that x402-compatible agents resolve automatically.
npm install @arcede/air-sdk
# No API key needed — the SDK handles x402 payment negotiation automatically.