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. The public contract is provider-neutral: Oncely routes across Brave, Serper, Exa, and Tavily and automatically fails over when an upstream route is unavailable.
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. Oncely first attempts its native reader, then automatically fails over across configured Jina Reader, Firecrawl, Bright Data Web Unlocker, and Exa routes.
4. Generate a video
Video generation is asynchronous. Submit once, then poll with the returned Oncely request_id. The balance reservation is captured only after DIT reports success and its actual cost; failed or expired jobs release the hold.
{
"prompt": "A cinematic sunrise over Shanghai",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}
POST /v1/tools/video.status/execute
{"request_id":"returned-oncely-request-id"}
5. 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
6. 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. For video, call oncely_video_generate and then oncely_video_status.
"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.