Base URL: https://agntos.dev Source: https://github.com/0xArtex/AgentOS

Quick Reference

All paid endpoints use x402 — make the request, get a 402, pay with USDC, done.

Authentication

Option A: Agent token (register once)

Authorization: Bearer aos_xxxxx

Option B: x402 payment (no registration needed) Just call any endpoint. The 402 response tells you what to pay. Payment = auth.

How x402 Works

1. Call any paid endpoint → get 402 Payment Required
2. Build a USDC transfer to the treasury address
3. Send it in the Payment-Signature header
4. Server verifies, settles on-chain, returns the response

Networks supported: Solana mainnet + Base (EVM)

Register Agent (Free)

curl -X POST https://agntos.dev/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "walletAddress": "YOUR_SOLANA_PUBKEY"}'

Returns token — save it: Authorization: Bearer aos_xxxxx

📱 Phone & SMS

Search Available Numbers (Free)

curl "https://agntos.dev/phone/numbers/search?country=US&limit=5"

Provision Number (2.00 USDC)

curl -X POST https://agntos.dev/phone/numbers \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"country": "US"}'

Response:

{
  "id": "uuid",
  "phoneNumber": "+14782058302",
  "country": "US",
  "owner": "your-agent",
  "active": true
}

Send SMS (0.05 USDC)

curl -X POST https://agntos.dev/phone/numbers/PHONE_ID/send \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15551234567", "body": "Hello from my agent!"}'

Read Messages (0.01 USDC)

curl https://agntos.dev/phone/numbers/PHONE_ID/messages \
  -H "Authorization: Bearer aos_xxxxx"

📞 Voice Calls

Place Outbound Call (0.10 USDC)

curl -X POST https://agntos.dev/phone/numbers/PHONE_ID/call \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "tts": "Hello! I am an AI agent calling you.",
    "ttsVoice": "female",
    "record": true
  }'

Response:

{
  "id": "uuid",
  "callControlId": "v3:xxxxx",
  "from": "+14782058302",
  "to": "+15551234567",
  "status": "initiated",
  "message": "Calling +15551234567 from +14782058302",
  "hint": "TTS will play when the call is answered"
}

Parameters:

• to (required) — phone number to call (E.164 format)
• tts — text-to-speech message to play when answered
• ttsVoice — voice: male or female
• audioUrl — URL of audio file to play when answered
• record — true to record the call
• timeoutSecs — ring timeout (default 30)

In-Call Actions

Once a call is connected, use the callControlId from the dial response:

Speak text (TTS) — 0.05 USDC:

curl -X POST https://agntos.dev/phone/calls/CALL_CONTROL_ID/speak \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "Please press 1 for sales or 2 for support", "voice": "female", "language": "en-US"}'

Play audio file — 0.05 USDC:

curl -X POST https://agntos.dev/phone/calls/CALL_CONTROL_ID/play \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"audioUrl": "https://example.com/greeting.mp3"}'

Send DTMF tones — 0.02 USDC:

curl -X POST https://agntos.dev/phone/calls/CALL_CONTROL_ID/dtmf \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"digits": "1234#"}'

Gather DTMF input — 0.05 USDC:

curl -X POST https://agntos.dev/phone/calls/CALL_CONTROL_ID/gather \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "maxDigits": 4,
    "terminatingDigit": "#",
    "prompt": "Please enter your PIN followed by the pound sign"
  }'

Start recording — 0.05 USDC:

curl -X POST https://agntos.dev/phone/calls/CALL_CONTROL_ID/record \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"format": "mp3"}'

Stop recording:

curl -X POST https://agntos.dev/phone/calls/CALL_CONTROL_ID/record/stop \
  -H "Authorization: Bearer aos_xxxxx"

Transfer call — 0.10 USDC:

curl -X POST https://agntos.dev/phone/calls/CALL_CONTROL_ID/transfer \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15559876543"}'

Answer inbound call:

curl -X POST https://agntos.dev/phone/calls/CALL_CONTROL_ID/answer \
  -H "Authorization: Bearer aos_xxxxx"

Hang up:

curl -X POST https://agntos.dev/phone/calls/CALL_CONTROL_ID/hangup \
  -H "Authorization: Bearer aos_xxxxx"

Call History

List calls for a number (0.01 USDC):

curl https://agntos.dev/phone/numbers/PHONE_ID/calls \
  -H "Authorization: Bearer aos_xxxxx"

Get call details (0.01 USDC):

curl https://agntos.dev/phone/calls/CALL_ID \
  -H "Authorization: Bearer aos_xxxxx"

Example: Agent calls a restaurant

1. POST /phone/numbers/PHONE_ID/call → {"to": "+15551234567", "tts": "Hi, I'd like to place an order"}
2. Wait for call.answered webhook
3. POST /phone/calls/CTRL_ID/gather → {"prompt": "Press 1 for English", "maxDigits": 1}
4. POST /phone/calls/CTRL_ID/dtmf → {"digits": "1"}
5. POST /phone/calls/CTRL_ID/speak → {"text": "I'd like to order two large pizzas for delivery"}
6. POST /phone/calls/CTRL_ID/hangup

📧 Email

Provision Inbox (1.00 USDC)

curl -X POST https://agntos.dev/email/inboxes \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "walletAddress": "YOUR_SOLANA_PUBKEY"}'

Returns: my-agent@agntos.dev

Read Inbox (0.01 USDC via x402)

curl https://agntos.dev/email/inboxes/INBOX_ID/messages

Send Email (0.05 USDC via x402)

curl -X POST https://agntos.dev/email/inboxes/INBOX_ID/send \
  -H "Content-Type: application/json" \
  -d '{"to": "user@example.com", "subject": "Hello", "body": "Message from my agent"}'

💻 Compute (VPS)

List Plans (Free)

curl https://agntos.dev/compute/plans

Available plans:

Upload SSH Key (0.10 USDC)

curl -X POST https://agntos.dev/compute/ssh-keys \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-key", "publicKey": "ssh-ed25519 AAAA..."}'

Returns id — use it when creating servers.

Create Server (5.00-95.00 USDC)

curl -X POST https://agntos.dev/compute/servers \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-server", "serverType": "cx23", "sshKeyIds": [KEY_ID]}'

Response:

{
  "id": "12345",
  "name": "my-server",
  "serverType": "cx23",
  "status": "running",
  "ipv4": "89.167.36.207",
  "message": "Server created. SSH in with: ssh root@89.167.36.207"
}

Zero-access design: You provide your SSH public key. We never see your private key. We can't access your server.

Server Actions (0.05 USDC)

curl -X POST https://agntos.dev/compute/servers/SERVER_ID/actions \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

Actions: reboot, poweron, poweroff, rebuild, reset

Resize Server (0.10 USDC)

curl -X POST https://agntos.dev/compute/servers/SERVER_ID/resize \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"serverType": "cx33"}'

Note: Server must be powered off to resize.

Delete Server (0.05 USDC)

curl -X DELETE https://agntos.dev/compute/servers/SERVER_ID \
  -H "Authorization: Bearer aos_xxxxx"

🌐 Domains

Check Availability (Free)

curl "https://agntos.dev/domains/check?domain=example.com"

Get Pricing (Free)

curl "https://agntos.dev/domains/pricing?domain=example"

Register Domain (dynamic pricing via x402)

curl -X POST https://agntos.dev/domains/register \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"domain": "my-agent.dev"}'

DNS Management (Free for owners)

# Get records
curl https://agntos.dev/domains/my-agent.dev/dns -H "Authorization: Bearer aos_xxxxx"

# Set records
curl -X POST https://agntos.dev/domains/my-agent.dev/dns \
  -H "Authorization: Bearer aos_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"records": [{"type": "A", "name": "@", "value": "1.2.3.4"}]}'

Payment Details

• Solana: USDC to B1YEboAH3ZDscqni7cyVnGkcDroB2kqLXCwLs3Ez8oX3
• Base (EVM): USDC to 0x7fA8aC4b42fd0C97ca983Bc73135EdbeA5bD6ab2
• x402 Version: 2
• Facilitator: 4R67MWivvc52g9BSzQRvQyD8GshttW1QLbnj46usBrcQ

Webhooks

Set up webhooks to receive events:

• SMS inbound: Messages to your number arrive via Telnyx webhook → stored, readable via API
• Voice events: call.initiated, call.answered, call.hangup, call.recording.saved, call.gather.ended
• Email inbound: Emails to *@agntos.dev processed via Cloudflare worker → stored encrypted