SMS

curl -X POST https://win.oneshotagent.com/v1/tools/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -d '{
    "message": "Your order has shipped! Track it at example.com/track/123",
    "to_number": "+14155551234"
  }'

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

// Single recipient
const result = await agent.sms({
  message: "Your order has shipped!",
  to_number: "+14155551234",
});

// Multiple recipients
const bulkResult = await agent.sms({
  message: "Team meeting moved to 3pm",
  to_number: ["+14155551234", "+14155555678", "+14155559012"],
});

{
  "error": "payment_required",
  "payment_request": {
    "chain_id": 8453,
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "0.0035",
    "recipient": "0x..."
  },
  "context": {
    "tool": "sms",
    "quote_id": "quote_sms_abc123",
    "recipient_count": 1,
    "message_length": 52,
    "segment_count": 1,
    "per_message_rate": "0.0035",
    "messaging_fee": "0.0035",
    "phone_registration_fee": "0.00",
    "total": "0.0035"
  }
}

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "tool": "sms",
  "message": "SMS queued for delivery.",
  "sms": {
    "to_numbers": ["+14155551234"],
    "segment_count": 1,
    "total_quoted": "0.0035"
  }
}

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "delivered": 1,
    "failed": 0,
    "total": 1,
    "status": "all_delivered"
  }
}

POST

tools

sms

send

curl -X POST https://win.oneshotagent.com/v1/tools/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -d '{
    "message": "Your order has shipped! Track it at example.com/track/123",
    "to_number": "+14155551234"
  }'

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

// Single recipient
const result = await agent.sms({
  message: "Your order has shipped!",
  to_number: "+14155551234",
});

// Multiple recipients
const bulkResult = await agent.sms({
  message: "Team meeting moved to 3pm",
  to_number: ["+14155551234", "+14155555678", "+14155559012"],
});

{
  "error": "payment_required",
  "payment_request": {
    "chain_id": 8453,
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "0.0035",
    "recipient": "0x..."
  },
  "context": {
    "tool": "sms",
    "quote_id": "quote_sms_abc123",
    "recipient_count": 1,
    "message_length": 52,
    "segment_count": 1,
    "per_message_rate": "0.0035",
    "messaging_fee": "0.0035",
    "phone_registration_fee": "0.00",
    "total": "0.0035"
  }
}

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "tool": "sms",
  "message": "SMS queued for delivery.",
  "sms": {
    "to_numbers": ["+14155551234"],
    "segment_count": 1,
    "total_quoted": "0.0035"
  }
}

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "delivered": 1,
    "failed": 0,
    "total": 1,
    "status": "all_delivered"
  }
}

Overview

Sends one text to one or more recipients (up to 10 per call), with automatic carrier routing. You pay per segment per recipient.

Authentication

Requires x402 payment. The first call returns a quote (402). The second call, with payment, sends.

Headers

string

Opt-in replay safety for the paid send (the request carrying X-Quote-ID). Pass any string up to 255 characters ([A-Za-z0-9_.:-]). Retrying the same key with the same to_number and message returns the original response without sending or charging again. The same key with a different to_number or message returns 422 idempotency_key_reuse, and a retry while the first request is still running returns 409 request_in_flight. The key is checked before the quote, so a retry that reuses the key replays even if it carries a new X-Quote-ID.Without a key, a quote still pays for one send: retrying with the same X-Quote-ID is rejected with 400 invalid_quote (quote already used), so you cannot tell from that retry whether the first send went out. Requesting a new quote and paying again sends the text again and charges again. Send an Idempotency-Key whenever you might retry.

Request Body

string

required

SMS message body. Maximum 1600 characters.

string | string[]

required

Phone number(s) in E.164 format (e.g., +14155551234). Maximum 10 recipients.

Quote Response (402)

string

Quote ID to include in the payment request

number

Number of recipients

number

Number of SMS segments (messages over 160 chars are split)

string

Rate per segment per recipient

string

Total cost in USD

Execution Response (202)

string

Job ID for tracking delivery

string

processing (messages are being sent)

string[]

Recipient numbers

number

Number of segments per message

Completed Job Result

number

Messages delivered

number

Failed deliveries

number

Total messages sent

string

all_delivered or partial_delivery

curl -X POST https://win.oneshotagent.com/v1/tools/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -d '{
    "message": "Your order has shipped! Track it at example.com/track/123",
    "to_number": "+14155551234"
  }'

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

// Single recipient
const result = await agent.sms({
  message: "Your order has shipped!",
  to_number: "+14155551234",
});

// Multiple recipients
const bulkResult = await agent.sms({
  message: "Team meeting moved to 3pm",
  to_number: ["+14155551234", "+14155555678", "+14155559012"],
});

{
  "error": "payment_required",
  "payment_request": {
    "chain_id": 8453,
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "0.0035",
    "recipient": "0x..."
  },
  "context": {
    "tool": "sms",
    "quote_id": "quote_sms_abc123",
    "recipient_count": 1,
    "message_length": 52,
    "segment_count": 1,
    "per_message_rate": "0.0035",
    "messaging_fee": "0.0035",
    "phone_registration_fee": "0.00",
    "total": "0.0035"
  }
}

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "tool": "sms",
  "message": "SMS queued for delivery.",
  "sms": {
    "to_numbers": ["+14155551234"],
    "segment_count": 1,
    "total_quoted": "0.0035"
  }
}

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "delivered": 1,
    "failed": 0,
    "total": 1,
    "status": "all_delivered"
  }
}

Message Segments

The character set decides how a message is split into segments:

Character Set	Segment Size
GSM-7 (standard)	160 characters
Unicode (emoji, special chars)	70 characters

The carrier reassembles long messages.

Error Handling

Content Blocked

{
  "error": "content_blocked",
  "message": "Content violates safety guidelines",
  "categories": ["spam"]
}

Moderation Unavailable (503)

{
  "error": "moderation_unavailable",
  "message": "Content moderation is temporarily unavailable, so this message was not sent. Retry shortly.",
  "retryable": true
}

A held send charges nothing: a payment already settled is returned as credit.

Emergency Number Blocked

{
  "error": "emergency_number_blocked",
  "message": "SMS to emergency services is not permitted",
  "blocked_number": "+1911"
}

See Pricing for SMS costs and segment sizing details.

Overview

Compute

Data

Monitoring

Research & Enrich

Messaging

Web & Browser

Build

Commerce

Account & billing

Other

Overview

Authentication

Headers

Request Body

Quote Response (402)

Execution Response (202)

Completed Job Result

Message Segments

Error Handling

​Overview

​Authentication

​Headers

​Request Body

​Quote Response (402)

​Execution Response (202)

​Completed Job Result

​Message Segments

​Error Handling

Overview

Authentication

Headers

Request Body

Quote Response (402)

Execution Response (202)

Completed Job Result

Message Segments

Error Handling