# AI Agents

Stable, fetchable reference for autonomous agents that need to discover Stakao, read the public agent API, pay with x402, and keep staking execution safely out of the public agent surface.

Last updated: 2026-07-08

Canonical HTML: https://stakao.com/docs/ai-agents
Raw Markdown: https://stakao.com/docs/ai-agents.md

## Table of contents

- 01. [Discovery surface](#discovery-surface)
- 02. [Agent API and x402 payments](#agent-api-x402)
- 03. [Safety, OAuth, and crawl boundaries](#security-crawl-boundaries)

## 01. Discovery surface

Agents should start from public, stable documents before attempting paid allocation calls.

The human site owns durable context: /docs, /docs/ai-agents, /docs/ai-agents.md, /llms.txt, /openapi.json, product metadata, and blog explainers. The API subdomain owns the narrow agent runtime surface at https://api.stakao.com/agent.

The split is intentional. Blog pages remain editorial SEO content, while docs pages become canonical reference input that agents can copy, fetch, cite, and convert into tool calls.

- Use /docs/ai-agents as the canonical human and crawler reference.
- Use /docs/ai-agents.md when an agent wants raw Markdown without layout.
- Use /llms.txt for site-wide context, priorities, safety boundaries, and links.
- Use https://api.stakao.com/agent for live API discovery, OpenAPI, MCP, price metadata, and x402 instructions.

### Fetch the public AI surfaces

```bash
curl -sS https://stakao.com/llms.txt
curl -sS https://stakao.com/docs/ai-agents.md
curl -sS https://api.stakao.com/agent \
  -H 'Accept: application/json'
curl -sS https://api.stakao.com/agent/openapi.json \
  -H 'Accept: application/openapi+json'
```

## 02. Agent API and x402 payments

The public API is intentionally small: it sells informational allocation analysis, not account access or staking execution.

Agents can request a direct model portfolio snapshot or a wallet-specific allocation analysis. The current public agent price is 3 USDC through x402 on Base.

For wallet-specific analysis, call free preflight first. The preflight response returns the Stakao-generated client_request_id that must be reused in the paid request body. Reusing that id with a different body returns a conflict instead of creating a second paid action.

- Direct model portfolio: GET /agent/allocation-analysis/model-portfolio.
- Wallet-specific flow: POST /agent/allocation-analysis/allocation/preflight, then POST /agent/allocation-analysis/allocation.
- Payment protocol: x402 v2.
- Payment rail: USDC on Base.
- Result: compact JSON with decision, product, and payment fields.

### Probe the direct paid model portfolio endpoint

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

### Start the wallet-specific preflight

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

## 03. Safety, OAuth, and crawl boundaries

Stakao keeps public agent commerce separate from private account operations and on-chain staking execution.

The public V1 agent API is informational only. A paid result can include the status ANALYZED, which means an analysis was stored. It does not mean that Stakao executed staking, created a delegate transaction, opened an account session, or gave investment advice.

Account-bound V2 surfaces require OAuth consent and remain separate from public x402 allocation analysis. MCP account tools are OAuth-only; public MCP tools are read-only.

On api.stakao.com, keep the Worker route surface exact: expose the root redirect, /agent, and /agent/*. Do not add a wildcard that exposes the full backend. The only WAF exception needed for the root probe is the exact root path.

- Public agent routes: https://api.stakao.com/agent and https://api.stakao.com/agent/*.
- Root probe: https://api.stakao.com/ redirects with 308 to /agent.
- Backend protection stays in place outside the Worker-owned agent surface.
- Dynamic OAuth Apps are disabled until account-bound monitoring, revocation, and cleanup are live.
- Pages that are empty, private, JSON-only, or backend-admin oriented should stay out of AI Search crawl targets.

### Exact Cloudflare WAF exception for root probe

```txt
http.host eq "api.stakao.com" and http.request.uri.path eq "/"
```

## Agent entrypoints

- [Human docs page](https://stakao.com/docs/ai-agents): Canonical HTML reference for humans, search engines, and agent browsers.
- [Raw Markdown](https://stakao.com/docs/ai-agents.md): Same reference content without layout, served as text/markdown.
- [llms.txt](https://stakao.com/llms.txt): Site-wide machine-readable Stakao context and crawl priorities.
- [Agent manifest](https://api.stakao.com/agent): Public api.stakao.com agent root for discovery and safety metadata.
- [Agent OpenAPI](https://api.stakao.com/agent/openapi.json): REST contract for agent allocation analysis endpoints.
- [Product MCP](https://api.stakao.com/agent/mcp): Read-only MCP endpoint for catalog, pricing, manifest, and safety tools.
- [Public content search MCP](https://stakao.search.ai.cloudflare.com/mcp): Cloudflare AI Search MCP over public Stakao content only.
- [Product catalog](https://stakao.com/.well-known/products.json): Discoverable product metadata for assistants and crawlers.

## Related Stakao references

- [Agent allocation manifest](https://api.stakao.com/agent/allocation-analysis): Machine-readable entrypoint for allocation analysis endpoints.
- [Direct model portfolio endpoint](https://api.stakao.com/agent/allocation-analysis/model-portfolio): x402-paid model portfolio analysis without wallet preflight.
- [OAuth account MCP](https://api.stakao.com/agent/mcp/account): Account-bound MCP endpoint requiring OAuth consent.
- [Strategies](https://stakao.com/strategies): Human-facing Stakao strategy catalog.
- [Pricing](https://stakao.com/pricing): Human plans, one-shot reports, add-ons, and agent API pricing context.
- [Allocation analysis](https://stakao.com/allocation-analysis): Human EUR one-shot wallet allocation report.

## Related blog articles

- [Agent-native staking API](https://stakao.com/blog/agent-native-staking-api): Editorial guide to the API surface and paid allocation flow.
- [x402 payments for AI agents](https://stakao.com/blog/x402-payments-for-ai-agents): HTTP 402 payment flow, USDC on Base, and retries.
- [MCP server for crypto staking agents](https://stakao.com/blog/mcp-server-for-crypto-staking-agents): Read-only tools for autonomous agents.
- [Agent-ready crypto staking platform](https://stakao.com/blog/agent-ready-crypto-staking-platform): Discovery, schema, AI Search, OpenAPI, MCP, and safety checklist.
- [Wallet allocation analysis](https://stakao.com/blog/wallet-allocation-analysis): Human and agent allocation products using the same analysis engine.