# Voxisim MCP
Endpoint: `https://api.voxisim.com/mcp`
Transport: Streamable HTTP with JSON-RPC responses
Supported protocol versions, newest first: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`
## Authentication and Discovery
MCP clients may use OAuth discovery or a `vxs_` bearer API key. Register a key at `POST https://api.voxisim.com/mcp/register`; it is returned exactly once. OAuth-capable clients should begin with [Protected Resource Metadata](https://api.voxisim.com/.well-known/oauth-protected-resource/mcp) and [Authorization Server Metadata](https://api.voxisim.com/.well-known/oauth-authorization-server).
Send credentials as `Authorization: Bearer YOUR_TOKEN`. After initialization, send the negotiated `MCP-Protocol-Version` header on subsequent requests. This server does not support JSON-RPC batches or server-initiated SSE streams.
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {"protocolVersion": "2025-11-25"}
}
```
Tool execution errors return `isError: true` and a shared `structuredContent.error` object. Purchase tools may instead return a typed `payment_required` x402 challenge; sign one accepted requirement and call the same tool again with its base64 authorization in `payment`.
Unlike REST, MCP always needs an account first — there is no accountless mode here. Fund that account with `topup_balance` (itself paid over x402: call it once without `payment` to get the requirements, then again with the signed authorization) and purchases will debit the balance with no further payments. Alternatively leave the balance empty: whenever it is short of the price, a buy tool answers `payment_required` and the `payment` argument pays for that one purchase. The challenge body is identical to the REST `402` — see [Paying for requests](https://voxisim.com/docs/api.md#paying) for how to read it, and note that activations are held rather than charged until an SMS arrives. If no SMS arrives within 20 minutes the activation is auto-refunded — the hold is released (x402) or the balance credited back (prepaid).
## Core
Account signup, balance and voucher redemption — shared by every product.
### get_account_balance
**Get account balance**
Returns the current USD balance and status of the authenticated account.
Input schema:
```json
{
"type": "object",
"properties": {},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"account_id",
"balance_usd",
"currency",
"status"
],
"properties": {
"status": {
"type": "string"
},
"currency": {
"type": "string",
"enum": [
"USD"
]
},
"account_id": {
"type": "string",
"format": "uuid"
},
"balance_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```
### topup_balance
**Top up the account balance**
Buy USD account balance with USDC over x402. Call without `payment` to get a `payment_required` result carrying the x402 requirements, sign one of them, then re-call with the signed authorization in `payment`. The credited balance funds later purchases with no per-call payment.
Input schema:
```json
{
"type": "object",
"required": [
"amount_usd"
],
"properties": {
"amount_usd": {
"type": "string",
"description": "USD amount of balance to buy, e.g. \"5.00\".",
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
},
"payment": {
"type": "string",
"description": "Base64 x402 payment authorization (the X-PAYMENT header value) that pays for the top-up."
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"credited_usd",
"balance_usd",
"currency"
],
"properties": {
"currency": {
"type": "string",
"enum": [
"USD"
]
},
"network": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"balance_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
},
"credited_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
},
"tx_hash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"x402Version",
"accepts",
"error",
"error_info",
"status"
],
"properties": {
"error": {
"type": "string",
"enum": [
"payment_required"
]
},
"error_info": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"payment_required"
]
},
"accepts": {
"type": "array",
"items": {
"type": "object",
"required": [
"scheme",
"network",
"maxAmountRequired",
"resource",
"description",
"mimeType",
"payTo",
"maxTimeoutSeconds",
"asset",
"extra"
],
"properties": {
"extra": {
"type": "object",
"additionalProperties": true
},
"scheme": {
"type": "string"
},
"description": {
"type": "string"
},
"resource": {
"type": "string"
},
"asset": {
"type": "string"
},
"maxAmountRequired": {
"type": "string"
},
"maxTimeoutSeconds": {
"type": "integer",
"minimum": 1
},
"mimeType": {
"type": "string"
},
"network": {
"type": "string"
},
"payTo": {
"type": "string"
}
},
"additionalProperties": false
}
},
"x402Version": {
"type": "integer",
"enum": [
1
]
}
},
"additionalProperties": false
}
]
}
```
### claim_voucher
**Claim a voucher**
Claim (redeem) a voucher code to add its USD value to the authenticated account's balance.
Input schema:
```json
{
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "The voucher code to claim.",
"minLength": 1
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"claimed",
"amount_usd",
"balance_usd",
"currency"
],
"properties": {
"currency": {
"type": "string",
"enum": [
"USD"
]
},
"balance_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
},
"amount_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
},
"claimed": {
"type": "boolean"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```
## SMS Activation
One-time numbers: a number that receives a single verification code and expires in ~20 minutes.
### sms_activation_list_services
**sms_activation_list_services**
One-time SMS numbers (a number that receives a single verification code and expires in ~20 minutes). List available services with their cheapest country and price. Flow: sms_activation_list_services -> sms_activation_list_countries -> sms_activation_buy_number -> poll sms_activation_get_code until done=true.
Input schema:
```json
{
"type": "object",
"properties": {},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"services"
],
"properties": {
"services": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"popular",
"title",
"category",
"count",
"min_price"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"popular": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"min_price": {
"anyOf": [
{
"type": "object",
"required": [
"price_usd",
"country"
],
"properties": {
"country": {
"type": "object",
"additionalProperties": true
},
"price_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```
### sms_activation_list_countries
**sms_activation_list_countries**
One-time SMS numbers. List countries available for a service, with price and availability.
Input schema:
```json
{
"type": "object",
"required": [
"service_id"
],
"properties": {
"service_id": {
"type": "string",
"description": "Service id from sms_activation_list_services"
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"countries"
],
"properties": {
"countries": {
"type": "array",
"items": {
"type": "object",
"required": [
"country_id",
"popular",
"iso",
"numbers_available",
"name",
"price_usd",
"activation_chance"
],
"properties": {
"name": {
"type": "string"
},
"iso": {
"type": "string"
},
"country_id": {
"type": "integer",
"minimum": 0
},
"activation_chance": {
"anyOf": [
{
"type": "object",
"required": [
"success_pct"
],
"properties": {
"success_pct": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"numbers_available": {
"type": "integer",
"minimum": 0
},
"popular": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"price_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```
### sms_activation_buy_number
**sms_activation_buy_number**
One-time SMS numbers. Buy a one-time number for a service+country. Pays from the account balance by default; if the balance is too low the tool returns a `payment_required` result with x402 payment requirements — re-call with a signed x402 authorization in `payment` to pay in USDC. Returns the id used to poll for the code.
Input schema:
```json
{
"type": "object",
"required": [
"service_id",
"country_id"
],
"properties": {
"service_id": {
"type": "string",
"minLength": 1
},
"country_id": {
"type": "integer",
"minimum": 0
},
"payment": {
"type": "string",
"description": "Optional base64 x402 payment authorization (the X-PAYMENT header value) to pay in USDC instead of balance."
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"id",
"number",
"number_h",
"info"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"info": {
"type": "object",
"required": [
"price_usd"
],
"properties": {
"price_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
}
},
"additionalProperties": false
},
"number": {
"type": "string"
},
"number_h": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"x402Version",
"accepts",
"error",
"error_info",
"status"
],
"properties": {
"error": {
"type": "string",
"enum": [
"payment_required"
]
},
"error_info": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"payment_required"
]
},
"accepts": {
"type": "array",
"items": {
"type": "object",
"required": [
"scheme",
"network",
"maxAmountRequired",
"resource",
"description",
"mimeType",
"payTo",
"maxTimeoutSeconds",
"asset",
"extra"
],
"properties": {
"extra": {
"type": "object",
"additionalProperties": true
},
"scheme": {
"type": "string"
},
"description": {
"type": "string"
},
"resource": {
"type": "string"
},
"asset": {
"type": "string"
},
"maxAmountRequired": {
"type": "string"
},
"maxTimeoutSeconds": {
"type": "integer",
"minimum": 1
},
"mimeType": {
"type": "string"
},
"network": {
"type": "string"
},
"payTo": {
"type": "string"
}
},
"additionalProperties": false
}
},
"x402Version": {
"type": "integer",
"enum": [
1
]
}
},
"additionalProperties": false
}
]
}
```
### sms_activation_get_code
**sms_activation_get_code**
One-time SMS numbers. Poll for the SMS code of a one-time number. Call repeatedly (every few seconds) until `done` is true or `codes` is non-empty.
Input schema:
```json
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Activation id (UUID) returned by sms_activation_buy_number"
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"status",
"codes",
"done"
],
"properties": {
"status": {
"type": "string"
},
"done": {
"type": "boolean"
},
"codes": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"code",
"text",
"inserted_at"
],
"properties": {
"code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"id": {
"type": "string",
"format": "uuid"
},
"text": {
"type": "string"
},
"inserted_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```
### sms_activation_list_numbers
**sms_activation_list_numbers**
One-time SMS numbers. List the current account's one-time numbers with their received codes.
Input schema:
```json
{
"type": "object",
"properties": {
"tab": {
"type": "string",
"enum": [
"active",
"archived"
]
},
"per_page": {
"type": "integer"
},
"last_id": {
"type": "string",
"description": "Pagination cursor (UUID) — the id of the last item from the previous page"
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"activations",
"cursor"
],
"properties": {
"cursor": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"activations": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"number",
"number_h",
"inserted_at",
"service_id",
"service",
"country",
"codes",
"refunded",
"pending",
"status"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"pending": {
"type": "boolean"
},
"status": {
"type": "string"
},
"service": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
},
"number": {
"type": "string"
},
"country": {
"type": "object",
"required": [
"country_id",
"iso",
"name"
],
"properties": {
"name": {
"type": "string"
},
"iso": {
"type": "string"
},
"country_id": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
},
"inserted_at": {
"type": "string",
"format": "date-time"
},
"service_id": {
"type": "string"
},
"codes": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"code",
"text",
"inserted_at"
],
"properties": {
"code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"id": {
"type": "string",
"format": "uuid"
},
"text": {
"type": "string"
},
"inserted_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"number_h": {
"type": "string"
},
"refunded": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```
## SMS Rental
Rented numbers: a number rented for hours or days that receives many SMS over time.
### sms_rental_list_services
**sms_rental_list_services**
Rented SMS numbers (a number rented for N hours/days that receives many SMS over time). List rentable services. Flow: sms_rental_list_services -> sms_rental_list_countries -> sms_rental_list_intervals (pick interval) -> sms_rental_buy_number -> poll sms_rental_get_codes; cancel/extend as needed.
Input schema:
```json
{
"type": "object",
"properties": {},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"services"
],
"properties": {
"services": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title",
"category",
"min_price",
"popular",
"count_all_total"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"popular": {
"type": "boolean"
},
"min_price": {
"type": "object",
"required": [
"price_usd",
"country",
"count_4",
"count_all"
],
"properties": {
"country": {
"type": "object",
"required": [
"id",
"iso",
"name"
],
"properties": {
"id": {
"type": "integer",
"minimum": 0
},
"name": {
"type": "string"
},
"iso": {
"type": "string"
}
},
"additionalProperties": false
},
"price_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
},
"count_4": {
"type": "integer",
"minimum": 0
},
"count_all": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
},
"count_all_total": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```
### sms_rental_list_countries
**sms_rental_list_countries**
Rented SMS numbers. List countries available to rent for a service.
Input schema:
```json
{
"type": "object",
"required": [
"service_id"
],
"properties": {
"service_id": {
"type": "string"
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"countries"
],
"properties": {
"countries": {
"type": "array",
"items": {
"type": "object",
"required": [
"country_id",
"iso",
"popular",
"name",
"count_4",
"count_all",
"price_usd"
],
"properties": {
"name": {
"type": "string"
},
"iso": {
"type": "string"
},
"country_id": {
"type": "integer",
"minimum": 0
},
"popular": {
"type": "boolean"
},
"price_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
},
"count_4": {
"type": "integer",
"minimum": 0
},
"count_all": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```
### sms_rental_list_intervals
**sms_rental_list_intervals**
Rented SMS numbers. List the rentable durations (interval in hours) and prices for a service+country.
Input schema:
```json
{
"type": "object",
"required": [
"service_id",
"country_id"
],
"properties": {
"service_id": {
"type": "string"
},
"country_id": {
"type": "integer"
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"count_all",
"intervals"
],
"properties": {
"count_all": {
"type": "integer",
"minimum": 0
},
"intervals": {
"type": "array",
"items": {
"type": "object",
"required": [
"hours",
"count",
"price_usd"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"hours": {
"type": "integer",
"minimum": 1
},
"price_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```
### sms_rental_buy_number
**sms_rental_buy_number**
Rented SMS numbers. Rent a number for a service+country for a given number of hours. Pays from the account balance by default; if the balance is too low the tool returns a `payment_required` result with x402 payment requirements — re-call with a signed x402 authorization in `payment` to pay in USDC.
Input schema:
```json
{
"type": "object",
"required": [
"service_id",
"country_id",
"hours"
],
"properties": {
"hours": {
"type": "integer",
"description": "Rental duration in hours (must match an available interval)"
},
"service_id": {
"type": "string"
},
"country_id": {
"type": "integer"
},
"payment": {
"type": "string",
"description": "Optional base64 x402 payment authorization (the X-PAYMENT header value) to pay in USDC instead of balance."
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"id",
"number",
"number_h",
"info"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"info": {
"type": "object",
"required": [
"price_usd"
],
"properties": {
"price_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
}
},
"additionalProperties": false
},
"number": {
"type": "string"
},
"number_h": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"x402Version",
"accepts",
"error",
"error_info",
"status"
],
"properties": {
"error": {
"type": "string",
"enum": [
"payment_required"
]
},
"error_info": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"payment_required"
]
},
"accepts": {
"type": "array",
"items": {
"type": "object",
"required": [
"scheme",
"network",
"maxAmountRequired",
"resource",
"description",
"mimeType",
"payTo",
"maxTimeoutSeconds",
"asset",
"extra"
],
"properties": {
"extra": {
"type": "object",
"additionalProperties": true
},
"scheme": {
"type": "string"
},
"description": {
"type": "string"
},
"resource": {
"type": "string"
},
"asset": {
"type": "string"
},
"maxAmountRequired": {
"type": "string"
},
"maxTimeoutSeconds": {
"type": "integer",
"minimum": 1
},
"mimeType": {
"type": "string"
},
"network": {
"type": "string"
},
"payTo": {
"type": "string"
}
},
"additionalProperties": false
}
},
"x402Version": {
"type": "integer",
"enum": [
1
]
}
},
"additionalProperties": false
}
]
}
```
### sms_rental_get_codes
**sms_rental_get_codes**
Rented SMS numbers. List the SMS messages received on a rented number. Poll periodically; new messages arrive over the lifetime of the rental.
Input schema:
```json
{
"type": "object",
"required": [
"rental_id"
],
"properties": {
"per_page": {
"type": "integer"
},
"last_id": {
"type": "string",
"description": "Pagination cursor (UUID) — the id of the last item from the previous page"
},
"rental_id": {
"type": "string",
"description": "Rental id (UUID) returned by sms_rental_buy_number"
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"codes",
"cursor"
],
"properties": {
"cursor": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"codes": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"from",
"body",
"inserted_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"body": {
"type": "string"
},
"from": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"inserted_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```
### sms_rental_list_numbers
**sms_rental_list_numbers**
Rented SMS numbers. List the current account's rented numbers with their most recent code.
Input schema:
```json
{
"type": "object",
"properties": {
"tab": {
"type": "string",
"enum": [
"active",
"archived"
]
},
"per_page": {
"type": "integer"
},
"last_id": {
"type": "string",
"description": "Pagination cursor (UUID) — the id of the last item from the previous page"
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"rents",
"cursor"
],
"properties": {
"cursor": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"rents": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"number",
"active",
"refundable",
"price_usd",
"service",
"country",
"inserted_at",
"rented_until",
"codes"
],
"properties": {
"active": {
"type": "boolean"
},
"id": {
"type": "string",
"format": "uuid"
},
"service": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
},
"number": {
"type": "string"
},
"country": {
"type": "object",
"required": [
"country_id",
"iso",
"name"
],
"properties": {
"name": {
"type": "string"
},
"iso": {
"type": "string"
},
"country_id": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
},
"inserted_at": {
"type": "string",
"format": "date-time"
},
"rented_until": {
"type": "string",
"format": "date-time"
},
"codes": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"from",
"body",
"inserted_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"body": {
"type": "string"
},
"from": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"inserted_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"price_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
},
"refundable": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```
### sms_rental_cancel
**sms_rental_cancel**
Rented SMS numbers. Cancel a rented number (refunds USD if within the refundable window).
Input schema:
```json
{
"type": "object",
"required": [
"rental_id"
],
"properties": {
"rental_id": {
"type": "string",
"description": "Rental id (UUID)"
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean",
"enum": [
true
]
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```
### sms_rental_extend
**sms_rental_extend**
Rented SMS numbers. Extend a rented number by N more hours. Deducts USD from the account balance.
Input schema:
```json
{
"type": "object",
"required": [
"rental_id",
"hours"
],
"properties": {
"hours": {
"type": "integer"
},
"rental_id": {
"type": "string",
"description": "Rental id (UUID)"
}
},
"additionalProperties": false
}
```
Structured output schema:
```json
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"rent"
],
"properties": {
"rent": {
"type": "object",
"required": [
"id",
"number",
"active",
"refundable",
"price_usd",
"service",
"country",
"inserted_at",
"rented_until",
"codes"
],
"properties": {
"active": {
"type": "boolean"
},
"id": {
"type": "string",
"format": "uuid"
},
"service": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
},
"number": {
"type": "string"
},
"country": {
"type": "object",
"required": [
"country_id",
"iso",
"name"
],
"properties": {
"name": {
"type": "string"
},
"iso": {
"type": "string"
},
"country_id": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
},
"inserted_at": {
"type": "string",
"format": "date-time"
},
"rented_until": {
"type": "string",
"format": "date-time"
},
"codes": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"from",
"body",
"inserted_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"body": {
"type": "string"
},
"from": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"inserted_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"price_usd": {
"type": "string",
"pattern": "^-?[0-9]+(?:\\.[0-9]+)?$"
},
"refundable": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"status",
"retry"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400
},
"type": {
"type": "string"
},
"retry": {
"type": "string",
"enum": [
"fix_request",
"retry",
"retry_later",
"never"
]
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}
```