Extend a StablePhone number by 30 days for $15.00 via USDC micropayment.
What it does
POST /api/number/topup extends an existing StablePhone phone number by 30 days from its current expiry date (or from today if already expired). The cost is $15.00 per top-up, settled via USDC on Base using x402 or MPP (Tempo) micropayment protocols. No API keys or accounts are required.
Top-ups stack: calling the endpoint multiple times prepays months ahead. Anyone can top up any number — you don't need to be the original purchaser. The request body requires a single field, `phone_number`, in E.164 format (e.g. +14155551234). The response returns the phone number and its new `expires_at` timestamp.
This endpoint is part of the StablePhone suite, which also offers AI phone calls ($0.54/call), phone number purchases ($20.00 for 30 days), and iMessage/FaceTime lookups ($0.05). Phone numbers acquired through StablePhone can be used as outbound caller IDs for AI-driven calls powered by Bland.ai. The endpoint accepts POST only; HEAD and GET return 405.
Capabilities
Use cases
- —Extending a dedicated AI-calling phone number before it expires
- —Prepaying multiple months of phone number rental in a single batch
- —Allowing a third party or agent to keep any StablePhone number active
- —Automating phone number lifecycle management in an agent workflow
Fit
Best for
- —AI agents that maintain persistent outbound caller IDs
- —Automated workflows needing unattended phone number renewal
- —Developers using x402/MPP micropayment rails without API keys
Not for
- —Purchasing a new phone number (use POST /api/number instead)
- —Making phone calls (use POST /api/call instead)
- —Non-US/CA phone numbers — only +1 numbers are supported
Quick start
curl -X POST https://stablephone.dev/api/number/topup \
-H "Content-Type: application/json" \
-d '{"phone_number": "+14155551234"}'
# Returns 402 — pay with an x402/MPP client, then resend to receive the new expiry.Example
Request
{
"phone_number": "+14155551234"
}Response
{
"success": true,
"expires_at": "2025-08-14T00:00:00.000Z",
"phone_number": "+14155551234"
}Endpoint
Quality
Full OpenAPI schema with request/response definitions, clear pricing ($15.00), detailed guidance docs, and well-documented payment protocols. The endpoint returned 405 on HEAD/GET probes, which is expected since it only accepts POST. No dedicated docs page exists (404), but the OpenAPI x-guidance and landing page provide thorough coverage.
Warnings
- —Probe returned 405 on HEAD and GET — endpoint is POST-only, which is consistent with the OpenAPI spec; not an availability issue.
- —No dedicated /docs page found (returns 404); all documentation comes from the OpenAPI spec and landing page.
- —Only US and CA phone numbers (+1) are supported.
Citations
- —Top-up costs $15.00 and extends the number by 30 days from current expiryhttps://stablephone.dev
- —Top-ups stack — call it multiple times to prepay months ahead. Anyone can top up any number.https://stablephone.dev
- —Payment via x402 (USDC on Base) or MPP with Tempo methodhttps://stablephone.dev
- —Phone number field requires E.164 format matching ^\+1\d{10}$https://stablephone.dev/.well-known/x402
- —Extends from current expiry or from today if already expiredhttps://stablephone.dev