Phone & Voice

Outbound AI voice calls, wallet-owned phone numbers and carrier lookups — for AI agents. No telecom account, no voice-AI signup, no carrier dashboard. Your wallet is the phone account.

Default country: US (no regulatory friction). Other countries can be requested via the country parameter — see Country availability below.

Voice AI and carrier numbers are provisioned by BlockRun's telephony stack, with x402 settlement at every step.

The Problem This Solves

An autonomous agent wants to call a restaurant to confirm a reservation, or call a vendor to verify a price. Traditionally that requires: a carrier account, a voice-AI account, KYC, a credit card, a long-lived API key, an outbound caller ID number you bought and manage, plus per-minute billing reconciliation.

BlockRun collapses all of it to two endpoints and one wallet:

1. POST /v1/phone/numbers/buy — $5.001, get a US number for 30 days (default; other countries via country parameter).
2. POST /v1/voice/call — $0.541, place an outbound call with an AI voice + a conversational task.

Wallet ownership is recorded by the gateway — only the wallet that bought a number can use it to place calls, and only that wallet can renew or release it. The number is bound to the chain it was bought on (base on blockrun.ai, solana on sol.blockrun.ai).

Endpoints

All prices include the flat $0.001 transaction fee. Every /v1/phone/* endpoint is POST with a JSON body; request bodies are validated strictly — an unknown key (for example area_code instead of areaCode) is a 400 Invalid request body with the offending keys listed in details. Validation runs before the 402, so an unpaid probe still needs a well-formed body.

POST /api/v1/phone/lookup and /lookup/fraud

Carrier information and line type for any phone number; the /fraud variant adds SIM-swap and call-forwarding signals.

Request Body

The upstream lookup result is returned as-is. If the carrier rejects the lookup, the 4xx is forwarded with its original status and you are not charged.

POST /api/v1/phone/numbers/buy

Provisions a new phone number from the carrier catalog in your chosen country, registers ownership against the calling wallet's address, and grants a 30-day lease. The purchase happens before settlement, so a failed purchase is never charged.

Request Body

Country availability

Most non-US/CA countries require per-country KYC documentation (address proof, business identity) before a number can be purchased. The approval is account-level — once it's in place for a country, all subsequent purchases work transparently.

If you need a number outside the US: call the endpoint with your desired country code. If the carrier rejects the purchase with a regulatory error, our gateway returns a 502 Purchase failed with the upstream message in details (not charged). Email care@blockrun.ai with the country you need — we'll complete the regulatory registration (usually 1–5 business days for carrier review) and let you know when the country is live.

Pricing is flat $5.001 / 30 days regardless of country (we absorb the carrier cost difference). Renewal also $5.001.

Response

{
  "phone_number": "+14155551234",
  "expires_at": "2026-06-17T12:00:00Z",
  "chain": "base",
  "message": "Number provisioned for 30 days. Use it as 'from' in voice calls."
}

The settlement transaction hash is in the X-Payment-Receipt response header (full receipt in X-Payment-Response). The returned phone_number can be used immediately as the from field on POST /v1/voice/call. After expires_at, the number is reclaimed and re-pooled (call renew before that to keep it).

If no number is available in the requested country / area code, the response is 404 No numbers available — not charged.

POST /api/v1/phone/numbers/renew

Extends an active number's lease by 30 days from its current expiry. Only the original owner wallet can renew, and only before the number expires — an expired number cannot be renewed; buy a new one.

Request Body

Response

{
  "phone_number": "+14155551234",
  "expires_at": "2026-07-17T12:00:00Z"
}

Errors

• 403 Forbidden with reason: "wrong_wallet" — the calling wallet doesn't own this number. The body carries payer_wallet so you can see which wallet actually signed.
• 403 Forbidden with reason: "expired" — the lease already lapsed; buy a new number.
• 403 Forbidden with reason: "not_found" — the number is not in our registry.

POST /api/v1/phone/numbers/list

Returns the phone numbers owned by the calling wallet (identity revealed via the x402 payer field). Send an empty JSON object {} as the body.

Response

{
  "numbers": [
    {
      "phone_number": "+14155551234",
      "chain": "base",
      "expires_at": "2026-06-17T12:00:00Z",
      "active": true
    }
  ],
  "count": 1
}

Expired numbers still appear with active: false until they are reclaimed.

POST /api/v1/phone/numbers/release

Releases a number you own back to the pool, immediately. Free — the request still goes through the x402 flow (a $0 authorization) so the gateway knows which wallet is asking.

Request Body

Response

{ "released": true, "phone_number": "+14155551234" }

403 Forbidden (reason: "wrong_wallet") if another wallet owns it; 404 Not Found if it isn't in the registry.

POST /api/v1/voice/call

Places an outbound AI conversation call. The AI voice agent dials the destination, follows the task you give it, and returns when the call ends (or hits the duration cap).

Request Body

The body is validated strictly (unknown keys → 400), and validation runs before the payment check — so the unpaid discovery request must already carry a valid to + task.

Response

{
  "call_id": "01HXY9...",
  "status": "queued",
  "poll_url": "https://blockrun.ai/api/v1/voice/call/01HXY9...",
  "message": "Call initiated. Poll poll_url for status, transcript, and recording."
}

The settlement transaction hash is in the X-Payment-Receipt header. The call is asynchronous — status: "queued" means dialing is about to start. Poll poll_url (GET /v1/voice/call/{call_id}) to track progress.

Errors

• 403 no_active_number — your wallet hasn't bought a number yet (or every number it owns has expired). Buy one at /v1/phone/numbers/buy; the body includes buy_endpoint.
• 403 Forbidden with reason: "wrong_wallet" / "not_found" — you passed a from you don't own. Response includes your_active_numbers (what your wallet does own).
• 403 Forbidden with reason: "expired" — the from number's lease lapsed; renew or buy a new one.
• 403 Forbidden — destination is an emergency-services number.
• 400 ambiguous_from — wallet owns multiple active numbers; specify from explicitly. Response includes your_active_numbers.
• 502 Call initiation failed — the voice provider refused to place the call. Not charged; upstream reason in details.

GET /api/v1/voice/call/{call_id}

Poll for call status, transcript, and final outcome. Free — no payment required (no X-Payment header needed).

Response

{
  "call_id": "01HXY9...",
  "from": "+14155551234",
  "to": "+12133610872",
  "status": "completed",
  "answered_by": "human",
  "call_length": 1.42,
  "call_ended_by": "USER",
  "ended_by": "USER",
  "ended_by_reason": "The callee (the person you called) hung up. This is normal — humans typically end calls once they've answered your question. Not a system error.",
  "summary": "Called Andy to ask him to take a break. Andy agreed and said he'd log off at 6pm.",
  "transcript": [
    { "role": "assistant", "text": "Hi Andy, this is Vicky's assistant calling..." },
    { "role": "user", "text": "Oh hey, what's up?" }
  ],
  "recording_url": "https://..."
}

The upstream call record is passed through as-is (field set may vary by call); BlockRun adds ended_by and ended_by_reason on top. status values: queued, started, ringing, in-progress, completed, error. Use ended_by rather than status to decide whether the call is finished.

An unknown call_id returns 404 Call not found. Requesting the literal {call_id} placeholder returns a 402-shaped discovery record (price.free: true) — substitute the real id.

ended_by — why the call ended

BlockRun synthesizes an ended_by field on the GET response so you can distinguish "the callee hung up" (normal) from "the system errored" (bug). Always check this field before assuming a failure.

If you keep seeing ended_by: USER and want longer conversations, update your task to give the AI a clearer exit instruction:

Call my friend Andy at +12133610872. Ask him whether he wants Italian or Sushi for dinner tonight. After he answers, confirm the restaurant choice back to him, then thank him politely and end the call. Do not keep talking past the answer.

Without an explicit "end the call after X" instruction, the AI tends to keep volunteering follow-up questions, and the callee — having already answered what they thought you wanted — hangs up first.

SDK Usage

Use Cases

1. Reservation confirmer ($0.541 per restaurant)

Agent calls a restaurant to confirm a booking. Hangs up after confirmation.

2. Vendor price-check bot ($0.541 per vendor)

Procurement agent calls suppliers, reads off a SKU, asks for current price + lead time, logs the answer.

3. AI receptionist for your wallet's inbound (coming soon)

The wallet-owned numbers can also receive inbound calls — feature is in development. Track awesome-blockrun/ROADMAP.md.

4. Wellness check bot ($0.541)

Agent calls a family member on a schedule, has a short conversation, summarizes the call into a Slack message.

5. Pre-dial hygiene ($0.011)

Run /v1/phone/lookup on a number before calling it: skip landlines that can't take an AI conversation, or use /lookup/fraud to flag recently SIM-swapped numbers before an agent reads out anything sensitive.

Pricing

All prices include the flat $0.001 transaction fee and are settled in USDC on Base (or Solana) via x402. The exact amount is always in the PAYMENT-REQUIRED / X-Payment-Required header of the 402 (accepts[0].amount, in USDC micro-units — 541000 for a call).

Why flat-rate for calls?

Competitors (StablePhone et al) charge $0.54 per minute — a 30-min call becomes $16+. BlockRun charges $0.541 per call regardless of length (up to the 30-min cap). The math:

• Short calls (<1 min, e.g. "is it open?"): we lose pennies, you win big.
• Long calls (15+ min): we eat the upstream per-minute cost, but the call cost is bounded for you.

This is intentional — autonomous agents need predictable per-action costs, not per-minute billing they have to model.

Required Setup

1. Fund your wallet with USDC on Base — at least $5.55 covers one number + one call.
2. Buy a number — first call creates it under your wallet's ownership.
3. Place a call — uses your owned number as caller ID automatically.

The number is owned by the wallet address that paid the buy x402. Lose your wallet's private key, you lose the number after expiry.

Limitations

• Number provisioning: US is the default and always works. Other countries are supported via the country parameter but typically require carrier regulatory (KYC) approval first — see Country availability. Request a country via care@blockrun.ai.
• Call destinations: any international destination the voice stack supports — no geo restriction on the to (callee) field, only on the from (caller-ID) number. Emergency-services numbers are always refused.
• Outbound only. Inbound receive is on the roadmap.
• 30-min hard cap per call. Longer dial-and-stay use cases require a custom integration.
• Preset voices only. Custom voice cloning is not available through the anonymous x402 flow yet.
• No SMS. Text messaging is intentionally not exposed (it requires sender registration that can't be done per-wallet).

Error Handling

Upstream 4xx on lookups is forwarded with its original status. Upstream calls time out after 30 seconds (15 seconds for status polls) and surface as 502 / 500, never charged.

What's next?

Also useful: Phone & Voice service page.