Build agents that can reach the web.
Oncely exposes provider-neutral HTTP tools. Every paid request requires an idempotency key, so retries never execute or charge twice.
1. Authenticate
Create a key in the console and send it as a Bearer token. Deployment test credentials are kept private and are never embedded in the page.
Idempotency-Key: req-unique-001
Content-Type: application/json
2. Search the web
-H 'Authorization: Bearer ak_live_...' \
-H 'Idempotency-Key: quickstart-001' \
-H 'Content-Type: application/json' \
-d '{"query":"agent payment protocols","max_results":5}'
Parameters: query (required, 1–1000 chars), max_results (1–20), freshness, domain filters, and include_content.
3. Read a page
{
"url": "https://example.com/article",
"format": "markdown",
"max_characters": 30000,
"include_links": true
}
Private networks, localhost, metadata endpoints, non-HTTP protocols, and oversized responses are rejected.
4. Pay with x402
Call the x402 route without a signature to receive an HTTP 402 and a base64-encoded x402 v2 PAYMENT-REQUIRED challenge. Sign locally, then retry with the same idempotency key. Successful calls return a base64-encoded settlement receipt in PAYMENT-RESPONSE.
PAYMENT-SIGNATURE: <signed authorization>
X-Payer-Wallet: 0x...
Idempotency-Key: wallet-request-001
5. MCP configuration
Point a compatible client at the gateway's authenticated MCP endpoint. Tool calls use their JSON-RPC request ID for idempotency and are billed at the same price as HTTP calls.
"mcpServers": {
"oncely": {
"url": "https://gateway.oncely.ai/mcp",
"headers": { "Authorization": "Bearer ak_live_..." }
}
}
}
Errors
Errors always include code, message, request_id, and retryable. Important codes include INVALID_API_KEY, INSUFFICIENT_BALANCE, RATE_LIMITED, PROVIDER_FAILED, PAYMENT_REQUIRED, and PAYMENT_REPLAYED.
Rate limits
The Demo gateway allows 60 requests per caller and tool each minute. Production limits can be set per user, key, wallet, IP, and tool, with Retry-After on HTTP 429.