Saperly

Saperly phone infrastructure for wallet-paid agent use. Agents can create hosted phone connections, provision numbers, send SMS, and place outbound calls without bringing their own Saperly API key.

Documentation

Payment protocol

x402

base

Method ledger

8 callable methods

POST/connections

0.01 USDC

Create a hosted Saperly phone connection.

POST JSON body. Protected by x402 exact payment. Returns the Saperly connection id.

{
  "body": {
    "agentName": "string (optional, default 'Saperly x402 agent')"
  }
}

POST/numbers

1.00 USDC

Provision a Saperly phone number.

POST JSON body. Protected by x402 exact payment. Number rent and upstream usage are handled by the FlyOS Saperly integration.

{
  "body": {
    "country": "string (optional, e.g. 'US')",
    "numberType": "local | mobile | tollFree (optional)",
    "areaCode": "string (optional)"
  }
}

POST/numbers/{numberId}/connection

0.01 USDC

Attach a phone number to a hosted Saperly connection.

Replace {numberId}. POST JSON body. Protected by x402 exact payment.

{
  "path": {
    "numberId": "string"
  },
  "body": {
    "connectionId": "string (required)"
  }
}

POST/numbers/{numberId}/release

0.01 USDC

Release a Saperly phone number.

Replace {numberId}. Protected by x402 exact payment.

{
  "path": {
    "numberId": "string"
  }
}

GET/messages

0.001 USDC

List SMS messages for a Saperly number.

GET with numberId query parameter. Protected by x402 exact payment.

{
  "query": {
    "numberId": "string (required)"
  }
}

POST/messages

0.05 USDC

Send an SMS from a Saperly number.

POST JSON body. Protected by x402 exact payment. Saperly compliance and consent checks still apply upstream.

{
  "body": {
    "fromNumberId": "string (required)",
    "to": "string (required, E.164)",
    "body": "string (required)"
  }
}

GET/calls

0.001 USDC

List calls for a Saperly number.

GET with numberId query parameter. Protected by x402 exact payment.

{
  "query": {
    "numberId": "string (required)"
  }
}

POST/calls

0.25 USDC

Place an outbound call from a Saperly number.

POST JSON body. Protected by x402 exact payment. Use a number provisioned through this service as fromNumberId.

{
  "body": {
    "fromNumberId": "string (required)",
    "to": "string (required, E.164)",
    "instructions": "string (optional)"
  }
}