# Voxisim > Voxisim is an all-in-one privacy and connectivity ecosystem, spanning virtual phone numbers, eSIM, global IP telephony, and security tools. Its core active service is Receive SMS, which lets users receive SMS verification codes on both free public numbers and paid private numbers from a wide range of countries, for apps like WhatsApp, Instagram, Tinder, and Amazon. ## Brand - [Home](https://voxisim.com/): Brand landing page introducing Voxisim and its services. ## Receive SMS Temporary phone numbers for receiving SMS verification codes (OTP) from any app or website, in a wide range of countries. Two options are available: free public numbers (shared with other users, inbox history may be visible to others, best for low-risk one-off signups) and paid private numbers (not shared, for accounts where privacy or reliability matters more) via Android / iOS App, or via REST API or MCP API. - [Receive SMS - overview](https://voxisim.com/services/receive-sms): Main service page; latest public numbers grouped by country. - [US numbers](https://voxisim.com/services/receive-sms/us): Temporary US phone numbers. - [Verify - service directory](https://voxisim.com/services/receive-sms/verify): Full list of apps/services that can be verified using a public number. - [WhatsApp verification](https://voxisim.com/services/receive-sms/verify/whatsapp): Receive WhatsApp SMS codes on a public number. - [Instagram verification](https://voxisim.com/services/receive-sms/verify/instagram): Receive Instagram SMS codes on a public number. - [Tinder verification](https://voxisim.com/services/receive-sms/verify/tinder): Receive Tinder SMS codes on a public number. - [Amazon verification](https://voxisim.com/services/receive-sms/verify/amazon): Receive Amazon SMS codes on a public number. - [iOS app](https://apps.apple.com/us/app/get-sms-code-verify/id6476933273): Mobile app for Receive SMS; includes paid private numbers in addition to free public numbers. - [Android app](https://play.google.com/store/apps/details?id=app.getsmscode): Mobile app for Receive SMS; includes paid private numbers in addition to free public numbers. ## API - Start Here - [Full developer context](https://voxisim.com/llms-full.txt): Self-contained REST and MCP documentation. - [REST API reference](https://voxisim.com/docs/api.md): Endpoints, schemas, authentication, x402, and errors. - [OpenAPI contract](https://api.voxisim.com/openapi.json): OpenAPI 3.0 JSON for code generation and validation. - [MCP reference](https://voxisim.com/docs/mcp.md): Connection, authentication, protocols, and tool schemas. - [MCP endpoint](https://api.voxisim.com/mcp): Streamable HTTP JSON-RPC endpoint. ## API - Paying Everything is paid in USDC over x402 (the EIP-3009 `exact` scheme). Pick one of two modes: - **Pay per request** — no account, no signup. POST the purchase with no credentials, read the `402` response's `accepts` array, sign one entry, then repeat the identical request with `X-PAYMENT: `. The first payment mints an account keyed to your wallet and returns its API key once as `receipt_token` — persist it, or you lose the ability to read back what you bought. - **Prepaid balance** — pay once, spend many times. `POST https://api.voxisim.com/v1/signup` for a `vxs_` key, then `POST https://api.voxisim.com/v1/balance/topup")}` with `{"amount_usd": "5.00"}` through the same `402` → sign → retry loop. Afterwards, purchases sent with the bearer key debit that balance and need no per-request payment. Voucher codes issued by Voxisim are redeemed with `POST https://api.voxisim.com/v1/vouchers/claim`. Prices are live — read them from the discovery operations and never hardcode them. See [Paying for requests](https://voxisim.com/docs/api.md#paying) for the full challenge format and settlement semantics. ## Voxisim REST API Base URL: `https://api.voxisim.com` Machine-readable contract: [OpenAPI 3.0 JSON](https://api.voxisim.com/openapi.json) ### Quick Start Create an account without authentication. The `vxs_` API key is returned exactly once: ```bash curl -X POST https://api.voxisim.com/v1/signup \ -H 'content-type: application/json' \ -d '{"label":"my-agent"}' ``` Send the returned key on authenticated requests: ```bash curl https://api.voxisim.com/v1/balance \ -H 'authorization: Bearer YOUR_VXS_API_KEY' ``` A fresh account has a zero balance, so read "Paying for requests" next before trying to buy anything. ### Paying for requests All payment is USDC over x402 (the EIP-3009 `exact` scheme). There are two ways to fund work, and both use the same `402` → sign → retry loop. #### Mode A — prepaid balance Sign up once, buy balance, then spend it with the bearer key. Purchases made this way carry no per-request payment. ```bash # 1. Ask for balance without paying — the server answers 402 with the requirements. curl -i -X POST https://api.voxisim.com/v1/balance/topup \ -H 'authorization: Bearer YOUR_VXS_API_KEY' \ -H 'content-type: application/json' \ -d '{"amount_usd":"5.00"}' # 2. Sign one `accepts` entry, then repeat the identical request with the authorization. curl -X POST https://api.voxisim.com/v1/balance/topup \ -H 'authorization: Bearer YOUR_VXS_API_KEY' \ -H 'content-type: application/json' \ -H 'X-PAYMENT: BASE64_SIGNED_AUTHORIZATION' \ -d '{"amount_usd":"5.00"}' ``` The top-up settles on-chain immediately and the response carries the new `balance_usd` plus the settlement's `tx_hash`. Authentication is optional here too: top up with no bearer key and the payer wallet gets a new account, whose API key comes back once as `receipt_token`. #### Mode B — pay per request Skip signup and pay for each purchase directly. Send the purchase with no credentials, take the `402`, sign, and repeat: ```bash curl -i -X POST https://api.voxisim.com/v1/sms/activation/numbers \ -H 'content-type: application/json' \ -d '{"service_id":"SERVICE_ID","country_id":0}' curl -X POST https://api.voxisim.com/v1/sms/activation/numbers \ -H 'content-type: application/json' \ -H 'X-PAYMENT: BASE64_SIGNED_AUTHORIZATION' \ -d '{"service_id":"SERVICE_ID","country_id":0}' ``` The first payment from an unseen wallet mints an account and returns `receipt_token` — the plaintext `vxs_` key, shown **exactly once**. Persist it: later purchases from the same wallet return `receipt_token: null`, and without the key you cannot read back the numbers you bought. #### Reading the 402 challenge The `402` body keeps the x402 spec's shape (`x402Version`, `accepts`) and carries this API's error object alongside under `error_info`. Each `accepts` entry is one payment option: ```json { "asset": "0xTOKEN_CONTRACT", "description": "Pay 0.24 for activation:SERVICE_ID:0", "extra": { "name": "USDC", "version": "2" }, "maxAmountRequired": "240000", "maxTimeoutSeconds": 1500, "mimeType": "application/json", "network": "base-sepolia", "payTo": "0xRECEIVING_WALLET", "resource": "activation:SERVICE_ID:0", "scheme": "exact" } ``` - There is one entry **per network this deployment accepts** (an EVM chain, a Solana chain, or several). Sign exactly one, and the payload you return must name that same `network`. - `maxAmountRequired` is in **atomic units**, not dollars: `price_usd × 10^decimals`, rounded up. USDC has 6 decimals, so 0.24 USD is `"240000"`. - Authorize at least `maxAmountRequired`; a lower `value` is rejected as `payment_invalid`. - `maxTimeoutSeconds` bounds how far ahead `validBefore` must sit. Activations get a wide window (see below); rentals and top-ups get a short one. - Send the signed payload base64-encoded in `X-PAYMENT` and **repeat the original request unchanged** — the server re-prices it and will reject a mismatch. - Each authorization is **single-use**: its `nonce` is recorded, so re-presenting one that already paid for something returns `payment_invalid`. Sign a fresh authorization per purchase or top-up. #### Hold versus settle This determines what a failed purchase actually costs, so budget against it: - **One-time activations are held, not charged.** The authorization is verified up front but only broadcast once an SMS actually arrives. If the number is refunded or expires without a code, the authorization is dropped and **you are charged nothing** — which is why the activation window is ~1500 seconds rather than ~120. **Auto-refund:** if no SMS arrives within 20 minutes the activation is cancelled automatically — the x402 authorization is released (never settled) and the number is freed. - **Rentals and top-ups settle immediately.** Money moves as part of the request, and the response carries an `X-PAYMENT-RESPONSE` header: base64 JSON with the on-chain `transaction`, `network`, and `payer`. If settlement fails after a rental was provisioned, the rental is cancelled upstream and the call returns `payment_failed`. Balance purchases behave differently again: they debit the account balance at purchase and, on refund, credit it back as store credit rather than returning funds on-chain. The same 20-minute auto-refund applies: if no SMS arrives, the balance is credited back automatically. ### Errors and Retry Policy REST errors use `{"error": {"type", "message", "status", "retry", "details"?}}`. Branch on `type` and use `retry` to decide whether to fix the request, retry, wait, or stop. | Type | HTTP status | Retry action | |---|---:|---| | `conflict` | 409 | `retry_later` | | `insufficient_balance` | 402 | `fix_request` | | `internal_error` | 500 | `retry` | | `invalid_argument` | 400 | `fix_request` | | `not_found` | 404 | `never` | | `out_of_stock` | 409 | `retry_later` | | `payment_failed` | 502 | `retry` | | `payment_invalid` | 400 | `fix_request` | | `payment_required` | 402 | `fix_request` | | `provider_error` | 502 | `retry` | | `provider_unavailable` | 503 | `retry_later` | | `rate_limited` | 429 | `retry_later` | | `unauthorized` | 401 | `fix_request` | | `unknown_tool` | 404 | `never` | | `voucher_invalid` | 422 | `never` | ### Core Account signup, balance and voucher redemption — shared by every product. #### GET /v1/balance **Get account balance** Operation ID: `getBalance` Authentication: Bearer token required Parameters: none Request body: none Responses: | Status | Schema | Description | |---|---|---| | `200` | [`BalanceResponse`](#balanceresponse) | Current account balance | | `401` | [`ErrorResponse`](#errorresponse) | Authentication required | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### POST /v1/balance/topup **Top up the account balance with x402** Operation ID: `topupBalance` Authentication: Optional bearer or x402 payment authorization Buys USD balance with an x402 (EIP-3009) USDC authorization. Send no `X-PAYMENT` header to receive the 402 challenge, sign one of its `accepts` entries, then repeat the request with the header. Authentication is optional: an unrecognised payer wallet mints an account and its API key is returned once as `receipt_token`. Parameters: - `X-PAYMENT` (header, optional, string) — Base64 x402 payment authorization Request body (required, `application/json`): [`TopupRequest`](#topuprequest) — Amount to buy Responses: | Status | Schema | Description | |---|---|---| | `200` | [`TopupResponse`](#topupresponse) | Balance credited | | `400` | [`ErrorResponse`](#errorresponse) | Invalid amount or payment | | `401` | [`ErrorResponse`](#errorresponse) | Authentication or x402 payment required | | `402` | [`PaymentRequiredResponse`](#paymentrequiredresponse) | Payment required | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `502` | [`ErrorResponse`](#errorresponse) | Payment service failed | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### POST /v1/signup **Create an API account** Operation ID: `signup` Authentication: Public Creates an account and returns its bearer API key exactly once. Parameters: none Request body (optional, `application/json`): [`SignupRequest`](#signuprequest) — Optional account label Responses: | Status | Schema | Description | |---|---|---| | `201` | [`SignupResponse`](#signupresponse) | Account created | | `400` | [`ErrorResponse`](#errorresponse) | Invalid signup request | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### POST /v1/vouchers/claim **Claim a voucher** Operation ID: `claimVoucher` Authentication: Bearer token required Parameters: none Request body (required, `application/json`): [`VoucherClaimRequest`](#voucherclaimrequest) — Voucher code Responses: | Status | Schema | Description | |---|---|---| | `200` | [`VoucherClaimResponse`](#voucherclaimresponse) | Voucher claimed | | `400` | [`ErrorResponse`](#errorresponse) | Invalid request | | `401` | [`ErrorResponse`](#errorresponse) | Authentication required | | `422` | [`ErrorResponse`](#errorresponse) | Voucher cannot be claimed | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | ### SMS Activation One-time numbers: a number that receives a single verification code and expires in ~20 minutes. #### GET /v1/sms/activation/countries **List countries for a one-time SMS service** Operation ID: `listActivationCountries` Authentication: Optional bearer Parameters: - `service_id` (query, required, string) — Service identifier Request body: none Responses: | Status | Schema | Description | |---|---|---| | `200` | [`ActivationCountriesResponse`](#activationcountriesresponse) | Available countries | | `400` | [`ErrorResponse`](#errorresponse) | Invalid service or request | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### GET /v1/sms/activation/numbers **List the account's one-time SMS numbers** Operation ID: `listActivations` Authentication: Bearer token required Parameters: - `tab` (query, optional, `active` \| `archived`) - `last_id` (query, optional, string(uuid)) — Pagination cursor - `per_page` (query, optional, integer, min 1, max 5000) Request body: none Responses: | Status | Schema | Description | |---|---|---| | `200` | [`ActivationListResponse`](#activationlistresponse) | Account activations | | `401` | [`ErrorResponse`](#errorresponse) | Authentication required | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### POST /v1/sms/activation/numbers **Buy a one-time SMS number** Operation ID: `buyActivationNumber` Authentication: Optional bearer or x402 payment authorization Pays from an authenticated account balance or with an x402 authorization. Parameters: - `X-PAYMENT` (header, optional, string) — Base64 x402 payment authorization Request body (required, `application/json`): [`ActivationPurchaseRequest`](#activationpurchaserequest) — Service and country Responses: | Status | Schema | Description | |---|---|---| | `201` | [`ActivationPurchaseResponse`](#activationpurchaseresponse) | Number purchased | | `400` | [`ErrorResponse`](#errorresponse) | Invalid request or payment | | `401` | [`ErrorResponse`](#errorresponse) | Authentication or x402 payment required | | `402` | [`PaymentRequiredResponse`](#paymentrequiredresponse) | Payment required | | `409` | [`ErrorResponse`](#errorresponse) | Number unavailable or request conflict | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `502` | [`ErrorResponse`](#errorresponse) | Provider or payment service failed | | `503` | [`ErrorResponse`](#errorresponse) | Provider unavailable | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### GET /v1/sms/activation/numbers/{id} **Get a one-time SMS number's status and codes** Operation ID: `getActivation` Authentication: Bearer token required Parameters: - `id` (path, required, string(uuid)) — Activation UUID Request body: none Responses: | Status | Schema | Description | |---|---|---| | `200` | [`ActivationStatusResponse`](#activationstatusresponse) | Activation status | | `401` | [`ErrorResponse`](#errorresponse) | Authentication required | | `404` | [`ErrorResponse`](#errorresponse) | Activation not found | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `502` | [`ErrorResponse`](#errorresponse) | Provider failed | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### GET /v1/sms/activation/services **List one-time SMS services** Operation ID: `listActivationServices` Authentication: Optional bearer Parameters: none Request body: none Responses: | Status | Schema | Description | |---|---|---| | `200` | [`ActivationServicesResponse`](#activationservicesresponse) | Available services | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `503` | [`ErrorResponse`](#errorresponse) | Provider unavailable | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | ### SMS Rental Rented numbers: a number rented for hours or days that receives many SMS over time. #### GET /v1/sms/rental/countries **List countries for a rental service** Operation ID: `listRentalCountries` Authentication: Optional bearer Parameters: - `service_id` (query, required, string) — Service identifier Request body: none Responses: | Status | Schema | Description | |---|---|---| | `200` | [`RentalCountriesResponse`](#rentalcountriesresponse) | Available countries | | `400` | [`ErrorResponse`](#errorresponse) | Invalid service or request | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### GET /v1/sms/rental/intervals **List rental durations and prices** Operation ID: `listRentalIntervals` Authentication: Optional bearer Parameters: - `service_id` (query, required, string) — Service identifier - `country_id` (query, required, integer, min 0) — Provider country identifier Request body: none Responses: | Status | Schema | Description | |---|---|---| | `200` | [`RentalIntervalsResponse`](#rentalintervalsresponse) | Available rental intervals | | `400` | [`ErrorResponse`](#errorresponse) | Invalid service, country, or request | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### GET /v1/sms/rental/numbers **List the account's rented SMS numbers** Operation ID: `listRentals` Authentication: Bearer token required Parameters: - `tab` (query, optional, `active` \| `archived`) - `last_id` (query, optional, string(uuid)) — Pagination cursor - `per_page` (query, optional, integer, min 1, max 5000) Request body: none Responses: | Status | Schema | Description | |---|---|---| | `200` | [`RentalListResponse`](#rentallistresponse) | Account rentals | | `401` | [`ErrorResponse`](#errorresponse) | Authentication required | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### POST /v1/sms/rental/numbers **Rent an SMS number** Operation ID: `buyRentalNumber` Authentication: Optional bearer or x402 payment authorization Pays from an authenticated account balance or with an x402 authorization. Parameters: - `X-PAYMENT` (header, optional, string) — Base64 x402 payment authorization Request body (required, `application/json`): [`RentalPurchaseRequest`](#rentalpurchaserequest) — Service, country, and duration Responses: | Status | Schema | Description | |---|---|---| | `201` | [`RentalPurchaseResponse`](#rentalpurchaseresponse) | Number rented | | `400` | [`ErrorResponse`](#errorresponse) | Invalid request or payment | | `401` | [`ErrorResponse`](#errorresponse) | Authentication or x402 payment required | | `402` | [`PaymentRequiredResponse`](#paymentrequiredresponse) | Payment required | | `409` | [`ErrorResponse`](#errorresponse) | Number unavailable or request conflict | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `502` | [`ErrorResponse`](#errorresponse) | Provider or payment service failed | | `503` | [`ErrorResponse`](#errorresponse) | Provider unavailable | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### POST /v1/sms/rental/numbers/{id}/cancel **Cancel a rental** Operation ID: `cancelRental` Authentication: Bearer token required Parameters: - `id` (path, required, string(uuid)) — Rental UUID Request body: none Responses: | Status | Schema | Description | |---|---|---| | `200` | [`RentalCancelResponse`](#rentalcancelresponse) | Rental cancelled | | `401` | [`ErrorResponse`](#errorresponse) | Authentication required | | `404` | [`ErrorResponse`](#errorresponse) | Rental not found | | `409` | [`ErrorResponse`](#errorresponse) | Rental cannot be cancelled yet | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `502` | [`ErrorResponse`](#errorresponse) | Provider failed | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### GET /v1/sms/rental/numbers/{id}/codes **List SMS received by a rental** Operation ID: `listRentalCodes` Authentication: Bearer token required Parameters: - `id` (path, required, string(uuid)) — Rental UUID - `last_id` (query, optional, string(uuid)) — Pagination cursor - `per_page` (query, optional, integer, min 1, max 5000) Request body: none Responses: | Status | Schema | Description | |---|---|---| | `200` | [`RentalCodesResponse`](#rentalcodesresponse) | Received SMS messages | | `401` | [`ErrorResponse`](#errorresponse) | Authentication required | | `404` | [`ErrorResponse`](#errorresponse) | Rental not found | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### POST /v1/sms/rental/numbers/{id}/extend **Extend a rental** Operation ID: `extendRental` Authentication: Bearer token required Parameters: - `id` (path, required, string(uuid)) — Rental UUID Request body (required, `application/json`): [`RentalExtendRequest`](#rentalextendrequest) — Extension duration Responses: | Status | Schema | Description | |---|---|---| | `200` | [`RentalExtendResponse`](#rentalextendresponse) | Rental extended | | `400` | [`ErrorResponse`](#errorresponse) | Invalid duration | | `401` | [`ErrorResponse`](#errorresponse) | Authentication required | | `402` | [`ErrorResponse`](#errorresponse) | Insufficient balance | | `404` | [`ErrorResponse`](#errorresponse) | Rental not found | | `409` | [`ErrorResponse`](#errorresponse) | Rental cannot be extended | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `502` | [`ErrorResponse`](#errorresponse) | Provider failed | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | #### GET /v1/sms/rental/services **List rentable SMS services** Operation ID: `listRentalServices` Authentication: Optional bearer Parameters: none Request body: none Responses: | Status | Schema | Description | |---|---|---| | `200` | [`RentalServicesResponse`](#rentalservicesresponse) | Available rental services | | `429` | [`ErrorResponse`](#errorresponse) | Rate limit exceeded | | `503` | [`ErrorResponse`](#errorresponse) | Provider unavailable | | `default` | [`ErrorResponse`](#errorresponse) | Unexpected error | ### Component Schemas Operations above reference these generated OpenAPI components. #### Activation ```json { "additionalProperties": false, "properties": { "codes": { "items": { "$ref": "#/components/schemas/ActivationCode" }, "type": "array" }, "country": { "$ref": "#/components/schemas/CountrySummary" }, "id": { "format": "uuid", "type": "string" }, "inserted_at": { "format": "date-time", "type": "string" }, "number": { "type": "string" }, "number_h": { "pattern": "^\\+?[0-9]+$", "type": "string" }, "pending": { "type": "boolean" }, "refunded": { "type": "boolean" }, "service": { "additionalProperties": true, "description": "Provider-owned service metadata; known fields may be extended without notice.", "properties": { "category": { "nullable": true, "type": "string" }, "icon_url": { "format": "uri", "nullable": true, "type": "string" }, "id": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "service_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "number", "number_h", "inserted_at", "service_id", "service", "country", "codes", "refunded", "pending", "status" ], "title": "Activation", "type": "object" } ``` #### ActivationCode ```json { "additionalProperties": false, "properties": { "code": { "nullable": true, "type": "string" }, "id": { "format": "uuid", "type": "string" }, "inserted_at": { "format": "date-time", "type": "string" }, "text": { "type": "string" } }, "required": [ "id", "code", "text", "inserted_at" ], "title": "ActivationCode", "type": "object" } ``` #### ActivationCountriesResponse ```json { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "activation_chance": { "additionalProperties": false, "nullable": true, "properties": { "success_pct": { "maximum": 100, "minimum": 0, "type": "integer" } }, "required": [ "success_pct" ], "type": "object" }, "country_id": { "minimum": 0, "type": "integer" }, "flag_url": { "format": "uri", "type": "string" }, "iso": { "type": "string" }, "name": { "type": "string" }, "numbers_available": { "minimum": 0, "type": "integer" }, "popular": { "nullable": true, "type": "boolean" }, "price_usd": { "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" } }, "required": [ "country_id", "popular", "iso", "flag_url", "numbers_available", "name", "price_usd", "activation_chance" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "title": "ActivationCountriesResponse", "type": "object" } ``` #### ActivationListResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "activations": { "items": { "$ref": "#/components/schemas/Activation" }, "type": "array" }, "cursor": { "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "activations", "cursor" ], "type": "object" } }, "required": [ "data" ], "title": "ActivationListResponse", "type": "object" } ``` #### ActivationPurchaseRequest ```json { "additionalProperties": false, "example": { "country_id": 187, "service_id": "tg" }, "properties": { "country_id": { "minimum": 0, "type": "integer" }, "service_id": { "minLength": 1, "type": "string" } }, "required": [ "service_id", "country_id" ], "title": "ActivationPurchaseRequest", "type": "object" } ``` #### ActivationPurchaseResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "info": { "additionalProperties": false, "properties": { "price_usd": { "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" } }, "required": [ "price_usd" ], "type": "object" }, "number": { "type": "string" }, "number_h": { "pattern": "^\\+?[0-9]+$", "type": "string" } }, "required": [ "id", "number", "number_h", "info" ], "type": "object" }, "receipt_token": { "nullable": true, "type": "string" } }, "required": [ "data" ], "title": "ActivationPurchaseResponse", "type": "object" } ``` #### ActivationServicesResponse ```json { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "category": { "nullable": true, "type": "string" }, "count": { "minimum": 0, "type": "integer" }, "icon_url": { "format": "uri", "nullable": true, "type": "string" }, "id": { "type": "string" }, "min_price": { "additionalProperties": false, "nullable": true, "properties": { "country": { "additionalProperties": true, "type": "object" }, "price_usd": { "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" } }, "required": [ "price_usd", "country" ], "type": "object" }, "popular": { "nullable": true, "type": "boolean" }, "title": { "type": "string" } }, "required": [ "id", "icon_url", "popular", "title", "category", "count", "min_price" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "title": "ActivationServicesResponse", "type": "object" } ``` #### ActivationStatusResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "codes": { "items": { "$ref": "#/components/schemas/ActivationCode" }, "type": "array" }, "done": { "type": "boolean" }, "status": { "type": "string" } }, "required": [ "status", "codes", "done" ], "type": "object" } }, "required": [ "data" ], "title": "ActivationStatusResponse", "type": "object" } ``` #### ApiError ```json { "additionalProperties": false, "example": { "message": "Invalid country_id", "retry": "fix_request", "status": 400, "type": "invalid_argument" }, "properties": { "details": { "additionalProperties": true, "type": "object" }, "message": { "maxLength": 201, "type": "string" }, "retry": { "enum": [ "fix_request", "never", "retry", "retry_later" ], "type": "string" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "type": { "enum": [ "conflict", "insufficient_balance", "internal_error", "invalid_argument", "not_found", "out_of_stock", "payment_failed", "payment_invalid", "payment_required", "provider_error", "provider_unavailable", "rate_limited", "unauthorized", "unknown_tool", "voucher_invalid" ], "type": "string" } }, "required": [ "type", "message", "status", "retry" ], "title": "ApiError", "type": "object" } ``` #### BalanceResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "account_id": { "format": "uuid", "type": "string" }, "balance_usd": { "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "type": "string" }, "currency": { "enum": [ "USD" ], "type": "string" }, "status": { "type": "string" } }, "required": [ "account_id", "balance_usd", "currency", "status" ], "type": "object" } }, "required": [ "data" ], "title": "BalanceResponse", "type": "object" } ``` #### CountrySummary ```json { "additionalProperties": false, "properties": { "country_id": { "minimum": 0, "type": "integer" }, "flag_url": { "format": "uri", "type": "string" }, "iso": { "type": "string" }, "name": { "type": "string" } }, "required": [ "country_id", "iso", "flag_url", "name" ], "title": "CountrySummary", "type": "object" } ``` #### ErrorResponse ```json { "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "retry": "fix_request", "status": 401, "type": "unauthorized" } }, "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ], "title": "ErrorResponse", "type": "object" } ``` #### PaymentRequiredResponse ```json { "description": "An account balance error or an x402 payment challenge.", "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/X402Challenge" } ], "title": "PaymentRequiredResponse" } ``` #### Rental ```json { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "codes": { "items": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "from": { "nullable": true, "type": "string" }, "id": { "format": "uuid", "type": "string" }, "inserted_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "from", "body", "inserted_at" ], "type": "object" }, "type": "array" }, "country": { "$ref": "#/components/schemas/CountrySummary" }, "id": { "format": "uuid", "type": "string" }, "inserted_at": { "format": "date-time", "type": "string" }, "number": { "pattern": "^\\+?[0-9]+$", "type": "string" }, "price_usd": { "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" }, "refundable": { "type": "boolean" }, "rented_until": { "format": "date-time", "type": "string" }, "service": { "additionalProperties": true, "description": "Provider-owned service metadata; known fields may be extended without notice.", "properties": { "category": { "nullable": true, "type": "string" }, "icon_url": { "format": "uri", "nullable": true, "type": "string" }, "id": { "type": "string" }, "title": { "type": "string" } }, "type": "object" } }, "required": [ "id", "number", "active", "refundable", "price_usd", "service", "country", "inserted_at", "rented_until", "codes" ], "title": "Rental", "type": "object" } ``` #### RentalCancelResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" } }, "required": [ "data" ], "title": "RentalCancelResponse", "type": "object" } ``` #### RentalCodesResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "codes": { "items": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "from": { "nullable": true, "type": "string" }, "id": { "format": "uuid", "type": "string" }, "inserted_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "from", "body", "inserted_at" ], "type": "object" }, "type": "array" }, "cursor": { "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "codes", "cursor" ], "type": "object" } }, "required": [ "data" ], "title": "RentalCodesResponse", "type": "object" } ``` #### RentalCountriesResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "countries": { "items": { "additionalProperties": false, "properties": { "count_4": { "minimum": 0, "type": "integer" }, "count_all": { "minimum": 0, "type": "integer" }, "country_id": { "minimum": 0, "type": "integer" }, "flag_url": { "format": "uri", "type": "string" }, "iso": { "type": "string" }, "name": { "type": "string" }, "popular": { "type": "boolean" }, "price_usd": { "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" } }, "required": [ "country_id", "iso", "popular", "flag_url", "name", "count_4", "count_all", "price_usd" ], "type": "object" }, "type": "array" } }, "required": [ "countries" ], "type": "object" } }, "required": [ "data" ], "title": "RentalCountriesResponse", "type": "object" } ``` #### RentalExtendRequest ```json { "additionalProperties": false, "example": { "hours": 4 }, "properties": { "hours": { "minimum": 1, "type": "integer" } }, "required": [ "hours" ], "title": "RentalExtendRequest", "type": "object" } ``` #### RentalExtendResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "rent": { "$ref": "#/components/schemas/Rental" } }, "required": [ "rent" ], "type": "object" } }, "required": [ "data" ], "title": "RentalExtendResponse", "type": "object" } ``` #### RentalIntervalsResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "count_all": { "minimum": 0, "type": "integer" }, "intervals": { "items": { "additionalProperties": false, "properties": { "count": { "minimum": 0, "type": "integer" }, "hours": { "minimum": 1, "type": "integer" }, "price_usd": { "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" } }, "required": [ "hours", "count", "price_usd" ], "type": "object" }, "type": "array" } }, "required": [ "count_all", "intervals" ], "type": "object" } }, "required": [ "data" ], "title": "RentalIntervalsResponse", "type": "object" } ``` #### RentalListResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "cursor": { "format": "uuid", "nullable": true, "type": "string" }, "rents": { "items": { "$ref": "#/components/schemas/Rental" }, "type": "array" } }, "required": [ "rents", "cursor" ], "type": "object" } }, "required": [ "data" ], "title": "RentalListResponse", "type": "object" } ``` #### RentalPurchaseRequest ```json { "additionalProperties": false, "example": { "country_id": 187, "hours": 4, "service_id": "tg" }, "properties": { "country_id": { "minimum": 0, "type": "integer" }, "hours": { "minimum": 1, "type": "integer" }, "service_id": { "minLength": 1, "type": "string" } }, "required": [ "service_id", "country_id", "hours" ], "title": "RentalPurchaseRequest", "type": "object" } ``` #### RentalPurchaseResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "info": { "additionalProperties": false, "properties": { "price_usd": { "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" } }, "required": [ "price_usd" ], "type": "object" }, "number": { "pattern": "^\\+?[0-9]+$", "type": "string" }, "number_h": { "pattern": "^\\+?[0-9]+$", "type": "string" } }, "required": [ "id", "number", "number_h", "info" ], "type": "object" }, "receipt_token": { "nullable": true, "type": "string" } }, "required": [ "data" ], "title": "RentalPurchaseResponse", "type": "object" } ``` #### RentalServicesResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "services": { "items": { "additionalProperties": false, "properties": { "category": { "nullable": true, "type": "string" }, "count_all_total": { "minimum": 0, "type": "integer" }, "icon_url": { "format": "uri", "nullable": true, "type": "string" }, "id": { "type": "string" }, "min_price": { "additionalProperties": false, "properties": { "count_4": { "minimum": 0, "type": "integer" }, "count_all": { "minimum": 0, "type": "integer" }, "country": { "additionalProperties": false, "properties": { "flag_url": { "format": "uri", "type": "string" }, "id": { "minimum": 0, "type": "integer" }, "iso": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "iso", "name", "flag_url" ], "type": "object" }, "price_usd": { "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" } }, "required": [ "price_usd", "country", "count_4", "count_all" ], "type": "object" }, "popular": { "type": "boolean" }, "title": { "type": "string" } }, "required": [ "id", "icon_url", "title", "category", "min_price", "popular", "count_all_total" ], "type": "object" }, "type": "array" } }, "required": [ "services" ], "type": "object" } }, "required": [ "data" ], "title": "RentalServicesResponse", "type": "object" } ``` #### SignupRequest ```json { "additionalProperties": false, "example": { "label": "production-agent" }, "properties": { "label": { "nullable": true, "type": "string" } }, "title": "SignupRequest", "type": "object" } ``` #### SignupResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "account_id": { "format": "uuid", "type": "string" }, "api_base": { "enum": [ "/v1" ], "type": "string" }, "api_key": { "pattern": "^vxs_", "type": "string" }, "balance_usd": { "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" }, "status": { "type": "string" } }, "required": [ "account_id", "api_key", "balance_usd", "status", "api_base" ], "type": "object" } }, "required": [ "data" ], "title": "SignupResponse", "type": "object" } ``` #### TopupRequest ```json { "additionalProperties": false, "example": { "amount_usd": "5.00" }, "properties": { "amount_usd": { "description": "USD amount of balance to buy.", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" } }, "required": [ "amount_usd" ], "title": "TopupRequest", "type": "object" } ``` #### TopupResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "balance_usd": { "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "type": "string" }, "credited_usd": { "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" }, "currency": { "enum": [ "USD" ], "type": "string" }, "network": { "nullable": true, "type": "string" }, "tx_hash": { "nullable": true, "type": "string" } }, "required": [ "credited_usd", "balance_usd", "currency" ], "type": "object" }, "receipt_token": { "nullable": true, "type": "string" } }, "required": [ "data" ], "title": "TopupResponse", "type": "object" } ``` #### VoucherClaimRequest ```json { "additionalProperties": false, "example": { "code": "VXS-PROMO-CODE" }, "properties": { "code": { "minLength": 1, "type": "string" } }, "required": [ "code" ], "title": "VoucherClaimRequest", "type": "object" } ``` #### VoucherClaimResponse ```json { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "amount_usd": { "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" }, "balance_usd": { "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "type": "string" }, "claimed": { "type": "boolean" }, "currency": { "enum": [ "USD" ], "type": "string" } }, "required": [ "claimed", "amount_usd", "balance_usd", "currency" ], "type": "object" } }, "required": [ "data" ], "title": "VoucherClaimResponse", "type": "object" } ``` #### X402Challenge ```json { "additionalProperties": false, "properties": { "accepts": { "items": { "$ref": "#/components/schemas/X402Requirement" }, "type": "array" }, "error": { "enum": [ "payment_required" ], "type": "string" }, "error_info": { "$ref": "#/components/schemas/ApiError" }, "x402Version": { "enum": [ 1 ], "type": "integer" } }, "required": [ "x402Version", "accepts", "error", "error_info" ], "title": "X402Challenge", "type": "object" } ``` #### X402Requirement ```json { "additionalProperties": false, "properties": { "asset": { "type": "string" }, "description": { "type": "string" }, "extra": { "additionalProperties": true, "type": "object" }, "maxAmountRequired": { "pattern": "^[0-9]+$", "type": "string" }, "maxTimeoutSeconds": { "minimum": 1, "type": "integer" }, "mimeType": { "enum": [ "application/json" ], "type": "string" }, "network": { "type": "string" }, "payTo": { "type": "string" }, "resource": { "type": "string" }, "scheme": { "type": "string" } }, "required": [ "scheme", "network", "maxAmountRequired", "resource", "description", "mimeType", "payTo", "maxTimeoutSeconds", "asset", "extra" ], "title": "X402Requirement", "type": "object" } ``` ## 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 } ] } ``` ## Legal and Product Context - [Terms of Service](https://voxisim.com/terms) - [Privacy Policy](https://voxisim.com/privacy) - [Public website](https://voxisim.com) ## Optional - [Privacy Policy](https://voxisim.com/privacy): How user and inbox data is handled. - [Terms of Service](https://voxisim.com/terms): Terms governing use of the public numbers and services.