Agent API authentication

Alphio Agent API will offer two authentication methods: API Key (subscription) and x402 (pay-as-you-go stablecoin).

Find it at: not yet publicly available. The flows below describe the design once early access opens.

warning

Authentication design is finalizing; details below are the current plan and may shift before public launch.

---

1. API Key authentication

The default path. You generate an API key from your Alphio Account, then send it as a Bearer token on every request.

Header format:

Authorization: Bearer <YOUR_API_KEY>

Key issuance:

• Generate keys from the Account page once Agent API is enabled for your tier.
• Each key is scoped to your user; you can create multiple keys per account.
• Keys can be labelled (e.g. "ci", "prod") for easy identification.

Key lifecycle:

• Rotate — generate a new key, deploy it, then delete the old key. Rotation is non-disruptive because both keys are valid until you revoke the old one.
• Revoke — instantly invalidate a key from the Account page. Existing requests with the revoked key fail with 401 Unauthorized.
• Expire — long-lived by default; expiry policies may be added per subscription tier.

API Key auth is bundled with paid subscriptions; quota scales with your tier.

---

2. x402 (pay-as-you-go)

x402 is a payment-on-request protocol that uses stablecoin (USDC) settlement, originally championed by Coinbase as an open standard for monetised HTTP. Each request includes a payment proof; the server verifies the payment on-chain and serves the response.

With x402 you don't need an Alphio subscription. You just need:

• A wallet with USDC
• A client capable of attaching x402 payment headers to each request

Why this matters for Agent API:

• No upfront billing relationship. Useful for one-off integrations, scripts, or experiments where signing up for a full subscription is overkill.
• Granular cost control. You pay only for requests you make; no monthly minimum.
• Stablecoin-native. USDC settlement fits the broader "agentic / on-chain" workflows Alphio targets.

x402 and API Key are mutually exclusive on a per-request basis — a single request uses one or the other, not both.

---

3. Security best practices

• Never embed keys in client-side code. Web pages, mobile apps, and browser extensions ship their source to users; any embedded API key becomes public. Call the Agent API from your backend and proxy responses to your clients.
• Rotate periodically. A monthly or quarterly rotation cadence is a good baseline. Treat any leaked key as compromised — revoke immediately.
• Use scoped / per-purpose keys. Create separate keys for separate environments (dev, CI, prod) and separate consumers. Revoking one key then only affects that consumer.
• Avoid logging the full key. When debugging, log only a prefix (e.g. first 6 characters) so logs don't become a leak vector.
• Watch for unusual traffic. Sudden quota spikes on a key are an early signal of compromise.

---

4. Rate limits

Rate limits apply per API key and per x402 wallet, independently of the subscription tier.

warning

Concrete per-second, per-minute, and per-day rate-limit numbers are still being finalized. Plan your client for backoff on 429 Too Many Requests; exact thresholds will be documented at GA.

Best practices regardless of the final numbers:

• Implement exponential backoff with jitter on 429.
• Cache responses where freshness allows — most Data API endpoints (calendars, fundamentals) update infrequently.
• Distribute load across keys for high-throughput integrations rather than hammering a single key.