# 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"
}
```