Skip to main content
POST
/
v1
/
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"
  }'

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

​
Overview

The SMS API enables AI agents to send text messages. Supports single or bulk sending with automatic carrier routing.

​
Authentication

Requires x402 payment. First call returns a quote (402), second call with payment executes.

​
Request Body

​
message
string
required
SMS message body. Maximum 1600 characters.
​
to_number
string | string[]
required
Phone number(s) in E.164 format (e.g., +14155551234). Maximum 10 recipients.

​
Quote Response (402)

​
context.quote_id
string
Quote ID to include in payment request
​
context.recipient_count
number
Number of recipients
​
context.segment_count
number
Number of SMS segments (messages over 160 chars split into segments)
​
context.per_message_rate
string
Rate per segment per recipient
​
context.total
string
Total cost in USD

​
Execution Response (202)

​
request_id
string
Job ID for tracking delivery status
​
status
string
processing - messages are being sent
​
sms.to_numbers
string[]
Recipient numbers
​
sms.segment_count
number
Number of segments per message

​
Completed Job Result

​
result.delivered
number
Number of successfully delivered messages
​
result.failed
number
Number of failed deliveries
​
result.total
number
Total messages sent
​
result.status
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"
  }'

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

​
Message Segments

SMS messages are split into segments:
Character SetSegment Size
GSM-7 (standard)160 characters
Unicode (emoji, special chars)70 characters
Long messages are automatically split and reassembled by the carrier.

​
Error Handling

Content Blocked
{
  "error": "content_blocked",
  "message": "Content violates safety guidelines",
  "categories": ["spam"]
}
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.