# x402 Payments

HTTP 402 payment flow for informational Stakao allocation analysis through USDC on Base.

Last updated: 2026-07-22

Canonical HTML: https://stakao.com/docs/x402
Raw Markdown: https://stakao.com/docs/x402.md

## Table of contents

- 01. [Payment rail](#payment-rail)
- 02. [Preflight before payment](#preflight)
- 03. [402, pay, retry](#retry)
- 04. [Payment safety](#payment-safety)

## 01. Payment rail

The Worker validates the request and returns the x402 challenge before forwarding a paid request to the backend.

- Protocol: x402 v2.
- Token: USDC.
- Network: Base, CAIP-2 eip155:8453.
- Price: 3 USDC for the paid Agent API analysis endpoints.
- No wallet is required for the direct model portfolio snapshot.

### Probe a direct payment challenge

```bash
curl -i 'https://api.stakao.com/agent/allocation-analysis/model-portfolio?catalog_item_id=quant_strat'
```

## 02. Preflight before payment

Wallet-specific analysis must complete the free preflight before the paid request is attempted.

- The response contains a Stakao-generated client_request_id.
- The paid body must reuse the exact wallet, catalog item, config, and client_request_id.
- Missing or unknown preflight ids return HTTP 428 and do not request payment.

### Create a quote

```bash
curl -sS -X POST 'https://api.stakao.com/agent/allocation-analysis/allocation/preflight' \
  -H 'Content-Type: application/json' \
  -d '{"wallet_address":"5YourBittensorWallet","catalog_item_id":"ai_agent","config":{}}'
```

## 03. 402, pay, retry

A valid request without payment returns HTTP 402 and exposes the payment requirements through x402 headers.

Read PAYMENT-REQUIRED (and the compatibility X-PAYMENT-REQUIRED header when present), pay the exact Base USDC requirement, then retry the identical HTTP request with the payment proof header. A successful response contains decision, product, and payment.

The Worker signs the forwarded request for the backend and binds the request body, query, entitlement, and payment proof. It never treats the internal signature as proof that settlement completed.

## 04. Payment safety

Payment purchases an informational analysis, not a staking action.

- The output status is ANALYZED, not RECOMMENDED, APPROVED, or EXECUTED.
- The response carries informational_only=true.
- No user strategy is activated and no delegate transaction is created.
- Errors include code, HTTP status in errors.json, retryable, remediation, and docs_url.

## Agent entrypoints

- [Agent manifest](https://api.stakao.com/agent): Worker-generated discovery manifest and safety metadata.
- [Agent OpenAPI](https://api.stakao.com/agent/openapi.json): Canonical REST contract generated by the Worker.
- [Agent llms.txt](https://api.stakao.com/agent/llms.txt): Worker-generated operational instructions.
- [Agent errors](https://api.stakao.com/agent/errors.json): Machine-readable error codes and remediation.
- [Public MCP](https://api.stakao.com/agent/mcp): Unauthenticated read-only MCP transport.

## Related Stakao references

- [AI Agents](https://stakao.com/docs/ai-agents): Start here for the complete agent flow.
- [Docs hub](https://stakao.com/docs): Canonical technical documentation index.
- [Full Markdown corpus](https://stakao.com/llms-full.txt): Complete docs and safety corpus.
- [Strategies Markdown](https://stakao.com/strategies.md): Generated strategy catalog.

## Related blog articles

- [Agent-native staking API](https://stakao.com/blog/agent-native-staking-api): Editorial context for the public agent API.
- [x402 payments for AI agents](https://stakao.com/blog/x402-payments-for-ai-agents): Editorial context for x402 payment retries.
- [MCP server for crypto staking agents](https://stakao.com/blog/mcp-server-for-crypto-staking-agents): Editorial context for the public MCP surface.