Quickstart

From zero to a waiting cell, then the first SMS after the handset claims. Tabs cover MCP, CLI, Python, and TypeScript.

Prerequisites

API access from agent sign-up. Keep AGENTCELL_API_KEY server-side.

Sign up + verify

POST /agent/sign-up then POST /agent/verify with the OTP sent to the owner.

Pay

x402 or MPP for agents; Stripe Checkout is optional for the human. 402 PAYMENT_REQUIRED until settled. Usage/activity before pay or any cell is 403 FLEET_REQUIRED.

Create a cell

POST /cells with display_name only (area_code optional). Do not pass client_id. Status is pending_provision; phone_number is empty. A phone order snapshots $229 / $79.

Wait for the device

Typically 1–72h. An operator sends AGENTCELL-SETUP from the connected admin handset; the default-SMS app claims (sideload / operator image — not Play Store). GET the cell until phone_number is set. Health is online when the radio WebSocket is connected.

Webhook + send

Set a webhook, then POST …/messages/send with Idempotency-Key. Empty number → 409 CELL_NOT_READY. No connected radio → 503 CARRIER_UNAVAILABLE.

Create a cell

import { AgentCell } from "@agentcell/sdk";

const client = new AgentCell({ apiKey: process.env.AGENTCELL_API_KEY });
const cell = await client.cells.create({
  displayName: "my-first-agent",
  areaCode: "415",
});
// cell.phoneNumber is empty until the handset claims
const got = await client.cells.get(cell.cell_id ?? cell.id);

First send (after the number exists)

await client.messages.send({
  cellId: cell.cell_id ?? cell.id,
  to: "+14155550144",
  body: "Hello from my agent",
  idempotencyKey: "hello-1",
});

Copy for Cursor / Claude

# AgentCell quickstart
export AGENTCELL_API_KEY=ac_...
# 1. agent_sign_up / agent_verify
# 2. pay (x402 | MPP | optional Stripe). FLEET_REQUIRED until pay or a cell exists.
# 3. create_cell — display_name only. No client_id. pending_provision, empty phone_number.
# 4. Wait 1–72h for operator setup SMS + device claim.
# 5. set webhook
# 6. send with Idempotency-Key. 409 CELL_NOT_READY / 503 CARRIER_UNAVAILABLE until radio is up.
# Full playbook: https://agentcell.store/docs/agent-onboarding.md