# Stakao Full Machine-Readable Corpus

Agent contract version: 2026-07-22

Contract and documentation corpus generated from the canonical docs registry.

## Machine-readable entrypoints

- Docs hub: https://stakao.com/docs
- Site context: https://stakao.com/llms.txt
- Strategies: https://stakao.com/strategies.md
- Authentication: https://stakao.com/auth.md
- Pricing: https://stakao.com/pricing.txt
- Agent manifest: https://api.stakao.com/agent
- Agent OpenAPI: https://api.stakao.com/agent/openapi.json
- Agent llms.txt: https://api.stakao.com/agent/llms.txt
- Agent errors: https://api.stakao.com/agent/errors.json
- Public MCP: https://api.stakao.com/agent/mcp
- OAuth account MCP: https://api.stakao.com/agent/mcp/account

## Safety rules

- Agent API: x402 USDC analysis, informational only, decision.status=ANALYZED.
- Agent Premium: human-activated strategy with limited proxy and periodic checks.
- OAuth account access: authorized reads and PENDING activation requests only.
- No external agent can sign, create a delegate transaction, or execute on-chain staking.
- Public machine-readable surfaces are reference input; private account and dashboard routes are not crawl targets.

## Docs pages

# Stakao Docs

Stable technical references for AI agents, developers, and AI crawlers. The blog remains editorial SEO content; /docs is the canonical reference surface for integrations and agent input.

## Pages

- [AI Agents](https://stakao.com/docs/ai-agents): Live. Canonical reference for agent discovery, x402 allocation analysis, MCP, OpenAPI, OAuth boundaries, and AI crawler input.
- [Agent API](https://stakao.com/docs/agent-api): Live. REST contracts for manifests, catalog, reference status, paid model portfolio snapshots, and wallet-specific allocation analysis.
- [x402 Payments](https://stakao.com/docs/x402): Live. HTTP 402 payment flow, USDC on Base, idempotent retries, payment proof, and audit records for autonomous agents.
- [MCP](https://stakao.com/docs/mcp): Live. Read-only MCP tools for catalog, pricing, manifest, safety metadata, public content search, and account-bound OAuth tools.
- [Allocation Analysis](https://stakao.com/docs/allocation-analysis): Live. Human EUR one-shot reports and agent-native JSON allocation outputs built from the same informational analysis engine.
- [OAuth & Security](https://stakao.com/docs/oauth): Live. OAuth metadata, protected resources, consent boundaries, origin protection, and public versus account-bound agent access.
- [Errors](https://stakao.com/docs/errors): Live. Machine-readable error codes, HTTP statuses, retryability, remediation, and compatibility fields for agent clients.

## Machine-readable entrypoints

- [AI Agents Markdown](https://stakao.com/docs/ai-agents.md): Raw Markdown reference for agent discovery and x402 allocation analysis.
- [Full Markdown corpus](https://stakao.com/llms-full.txt): Complete machine-readable corpus of the canonical docs and safety rules.
- [Agent errors](https://api.stakao.com/agent/errors.json): Worker-generated error catalog with remediation metadata.
- [Strategies Markdown](https://stakao.com/strategies.md): Machine-readable strategy catalog generated from the product catalog.
- [Pricing Markdown](https://stakao.com/pricing.txt): Machine-readable pricing and agent payment context.
- [llms.txt](https://stakao.com/llms.txt): Site-wide machine-readable Stakao context.
- [Agent manifest](https://api.stakao.com/agent): API subdomain discovery root.


## Canonical docs

# AI Agents

Agent-first, fetchable reference for discovering Stakao, paying for informational allocation analysis, using OAuth account reads, and keeping staking execution outside the public Agent API.

Last updated: 2026-07-22

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. [Start here](#start-here)
- 03. [Agent API and x402 payments](#agent-api-x402)
- 04. [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, the Markdown version of every docs page, /llms.txt, /llms-full.txt, /strategies.md, /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 /llms-full.txt when the full canonical corpus is needed in one context window.
- 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. Start here

The complete agent flow is discover → catalog → reference status → preflight → HTTP 402 → payment → retry → structured result.

Discovery and catalog calls are free. Reference status determines whether a four-hour analysis is available. Preflight validates wallet-specific requests before payment. A fresh payable request returns HTTP 402; the agent reads the x402 headers, pays in USDC on Base, retries the exact request, and receives a structured informational result.

### Fetch the full machine-readable entrypoints

```bash
curl -sS https://api.stakao.com/agent/llms.txt
curl -sS https://stakao.com/llms-full.txt
curl -sS https://api.stakao.com/agent/errors.json
```

## 03. 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": {}
  }'
```

## 04. Safety, OAuth, and crawl boundaries

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

The 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.

The Agent Premium product is different: a human activates it, it uses a limited staking-only proxy and periodic checks, and it may execute the human-authorized staking workflow. Agent API OAuth/account access remains data-scoped and human-gated; it cannot execute on-chain operations.

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.
- [Agent errors](https://api.stakao.com/agent/errors.json): Machine-readable error codes and remediation hints.
- [Full Markdown corpus](https://stakao.com/llms-full.txt): Complete canonical documentation corpus.
- [OAuth account profile](https://api.stakao.com/agent/account/me): OAuth-protected account endpoint; openid scope.
- [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.


---

# Agent API

The Worker-owned public contract for Stakao discovery, allocation analysis, x402 payments, OAuth account reads, and safety boundaries.

Last updated: 2026-07-22

Canonical HTML: https://stakao.com/docs/agent-api
Raw Markdown: https://stakao.com/docs/agent-api.md

## Table of contents

- 01. [Canonical contract](#canonical-contract)
- 02. [Start here](#start-here)
- 03. [Public surfaces](#surfaces)
- 04. [Account boundary](#account-boundary)

## 01. Canonical contract

Contract version 2026-07-22 is served by api.stakao.com/agent. The Worker is the source of truth for routes, methods, schemas, statuses, prices, authentication, and errors.

Read https://api.stakao.com/agent first. The manifest links to the Worker OpenAPI, llms.txt, errors.json, MCP card, catalog, account routes, and safety metadata. The site OpenAPI remains the general Stakao commerce document; agent schemas live in https://api.stakao.com/agent/openapi.json.

The public Agent API is separate from the human Agent Premium product. The API can return informational allocation analysis; it cannot activate a strategy, create a delegate transaction, sign a wallet action, or execute staking.

- Public analysis responses use decision.status=ANALYZED and decision.informational_only=true.
- The API payment rail is x402 USDC on Base at 3 USDC for the paid allocation endpoints.
- Account-bound routes require OAuth and active Stakao consent.
- Activation requests are human-reviewed and remain PENDING.

## 02. Start here

The operational path is deterministic and can be executed with ordinary HTTP clients.

### Discover the contract

```bash
curl -sS https://api.stakao.com/agent
curl -sS https://api.stakao.com/agent/openapi.json
curl -sS https://api.stakao.com/agent/errors.json
```

### Wallet-specific paid flow

```text
discover → catalog → reference status → preflight → HTTP 402 → payment → retry → structured result
```

## 03. Public surfaces

Only the routes declared by the Worker contract are public Agent API routes.

- GET https://api.stakao.com/agent/allocation-analysis/catalog — product metadata with absolute product_url, activation_url, and cta_href.
- GET https://api.stakao.com/agent/allocation-analysis/reference-status — four-hour reference freshness.
- POST https://api.stakao.com/agent/allocation-analysis/allocation/preflight — free validation and quote.
- GET https://api.stakao.com/agent/allocation-analysis/model-portfolio — direct x402 model portfolio snapshot.
- POST https://api.stakao.com/agent/allocation-analysis/allocation — wallet-specific x402 analysis.
- GET/POST https://api.stakao.com/agent/mcp and GET/POST https://api.stakao.com/agent/search — public discovery and search transports.

## 04. Account boundary

OAuth account access is additive and cannot widen the public x402 surface.

Account reads are available at https://api.stakao.com/agent/account/me, https://api.stakao.com/agent/account/wallets, and https://api.stakao.com/agent/account/strategies. https://api.stakao.com/agent/mcp/account exposes the same account operations through OAuth-protected MCP JSON-RPC.

The activation endpoint https://api.stakao.com/agent/account/activation-requests and the account MCP request_activation tool create only a PENDING human-review request. Agent API and Agent Premium are different products: Premium is activated by a human and may use limited proxy execution; Agent API is informational only.

## 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.


---

# 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.


---

# MCP

MCP transport and tool boundaries for public discovery and OAuth-protected account operations.

Last updated: 2026-07-22

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

## Table of contents

- 01. [Public MCP card](#public-card)
- 02. [Public tools](#public-tools)
- 03. [Account MCP](#account-mcp)
- 04. [JSON-RPC safety](#json-rpc-safety)

## 01. Public MCP card

https://api.stakao.com/agent/mcp is a public read-only streamable HTTP JSON-RPC endpoint.

- Public tools expose catalog, manifest, pricing, x402 instructions, safety metadata, and public content search.
- Public MCP does not expose account data and does not require OAuth.
- The card advertises ANALYZED and informational_only=true.

### Read the public card

```bash
curl -sS https://api.stakao.com/agent/mcp
```

### Initialize

```bash
curl -sS -X POST https://api.stakao.com/agent/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
```

## 02. Public tools

Use tools/list after initialize to discover the exact public tool schemas.

- get_stakao_catalog
- get_agent_manifest
- get_paid_allocation_instructions
- get_reference_allocation_status
- explain_strategy
- quote_allocation_product
- quote_model_portfolio_snapshot
- search_public_content

## 03. Account MCP

https://api.stakao.com/agent/mcp/account is a separate OAuth-protected MCP transport for authorized account data.

The Worker requires a bearer token before initialize, tools/list, or tools/call, then validates the token and active Stakao consent through the backend account profile route.

- get_account_profile — requires openid.
- list_wallets — requires openid profile and returns only owned wallets.
- list_strategies — requires openid profile and returns only owned strategies.
- request_activation — requires openid profile email and creates PENDING only.

## 04. JSON-RPC safety

Both transports validate JSON-RPC 2.0 envelopes and bound batch sizes.

- Malformed envelopes return an HTTP error before tool dispatch.
- Account MCP batches cannot contain multiple request_activation mutations.
- No MCP tool signs, creates a proxy, submits a transaction, or executes on-chain staking.
- Bearer tokens, OAuth bodies, and account data are not written to Worker logs.

## 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.


---

# Allocation Analysis

Catalog, reference freshness, preflight, payment, and structured response semantics for Stakao allocation analysis.

Last updated: 2026-07-22

Canonical HTML: https://stakao.com/docs/allocation-analysis
Raw Markdown: https://stakao.com/docs/allocation-analysis.md

## Table of contents

- 01. [Catalog and reference](#catalog)
- 02. [Wallet-specific preflight](#preflight-flow)
- 03. [Structured result](#structured-result)
- 04. [Execution boundary](#execution-boundary)

## 01. Catalog and reference

Start with https://api.stakao.com/agent/allocation-analysis/catalog and https://api.stakao.com/agent/allocation-analysis/reference-status.

The Worker normalizes catalog links to absolute HTTPS URLs so an agent can follow product, activation, and CTA links without guessing the human origin. Reference status reports whether the four-hour model portfolio snapshot is fresh enough to request payment.

### Inspect the free surfaces

```bash
curl -sS https://api.stakao.com/agent/allocation-analysis/catalog
curl -sS https://api.stakao.com/agent/allocation-analysis/reference-status
```

## 02. Wallet-specific preflight

Preflight validates the request before any payment is requested.

- Validate the Bittensor wallet address and readable balance.
- Resolve the server-owned catalog item and accepted configuration.
- Check reference freshness and analysis availability.
- Return a Stakao-generated quote id for the paid retry.

## 03. Structured result

The paid response is intentionally compact and machine-readable.

- decision.status is ANALYZED.
- decision.informational_only is true.
- payment records the x402 rail and completed payment context.
- The result is not investment advice and is not an execution instruction.

### Response shape

```json
{"decision":{"status":"ANALYZED","informational_only":true},"product":{},"payment":{}}
```

## 04. Execution boundary

The Agent API and the human Agent Premium product share analysis context but not permissions.

Agent Premium is enabled by a human and may run a limited staking-only proxy workflow with recurring checks. Agent API allocation analysis is anonymous/x402 or account-read OAuth, informational only, and cannot activate or execute staking.

## 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.


---

# OAuth & Security

OAuth consent, account route scopes, bearer forwarding, cache policy, and the boundary between account access and execution.

Last updated: 2026-07-22

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

## Table of contents

- 01. [Consent and credentials](#consent)
- 02. [Route scopes](#scopes)
- 03. [Proxy and cache policy](#proxy-policy)
- 04. [No agent execution](#no-execution)

## 01. Consent and credentials

Account-bound access requires a Supabase OAuth 2.1 bearer token and active Stakao consent for the token client_id.

Public discovery, catalog, search, MCP, and x402 allocation analysis do not require OAuth. OAuth is used only when an agent requests account-bound data or submits a human-reviewed activation request.

### Account request

```bash
curl -i https://api.stakao.com/agent/account/me \
  -H 'Authorization: Bearer <supabase-oauth-access-token>'
```

## 02. Route scopes

The backend enforces both token scopes and the scopes stored in the active Stakao consent.

- GET https://api.stakao.com/agent/account/me — openid.
- GET https://api.stakao.com/agent/account/wallets — openid profile.
- GET https://api.stakao.com/agent/account/strategies — openid profile.
- POST https://api.stakao.com/agent/account/activation-requests — openid profile email.
- GET/POST https://api.stakao.com/agent/mcp/account — openid profile transport access; tool-specific calls enforce their account scope.

## 03. Proxy and cache policy

The Worker forwards Authorization only on exact account routes and never caches account responses.

- Public x402 and public MCP requests have Authorization removed before origin forwarding.
- Account responses use Cache-Control: private, no-store.
- 401 responses preserve or synthesize WWW-Authenticate: Bearer.
- Cookies, bearer tokens, OAuth bodies, and account payloads are excluded from Worker logs.

## 04. No agent execution

OAuth account access does not grant on-chain execution authority.

Account reads are tenant-scoped to the authenticated user. request_activation creates a PENDING record for human review. It does not sign, create a proxy, create a delegate transaction, write user_strategies, or call the chain.

## 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.
- [Auth reference](https://stakao.com/auth.md): Raw authentication and payment reference.

## 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.


---

# Errors

Machine-readable Agent API errors with HTTP status, retryability, remediation, and compatibility fields.

Last updated: 2026-07-22

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

## Table of contents

- 01. [Canonical catalog](#catalog-shape)
- 02. [Compatibility fields](#compatibility)
- 03. [Retry semantics](#retry)
- 04. [Unknown routes](#unknown-routes)

## 01. Canonical catalog

Fetch https://api.stakao.com/agent/errors.json for the Worker-generated error definitions tied to contract version 2026-07-22.

- invalid_request — 400.
- payment_required — 402.
- auth_required — 401.
- insufficient_scope — 403.
- not_found — 404.
- request_conflict — 409.
- preflight_required — 428.
- body_too_large — 413.
- rate_limited — 429.
- reference_unavailable — 503.
- origin_unavailable — 502/503.

### Error definition

```json
{"code":"preflight_required","http_status":428,"retryable":false,"remediation":"Call the free preflight endpoint first.","docs_url":"https://stakao.com/docs/errors"}
```

## 02. Compatibility fields

Existing response fields remain available while canonical fields are added.

Error responses keep the legacy error field for existing clients. They also include code, retryable, remediation, and docs_url. JSON-RPC errors retain the JSON-RPC error object and use HTTP status only for transport-level failures.

## 03. Retry semantics

Use retryable and remediation together; do not blindly retry authentication or validation errors.

- payment_required: read the x402 challenge, pay, and retry the exact request.
- rate_limited: wait for Retry-After before retrying.
- reference_unavailable or origin_unavailable: retry later and do not make a payment assumption.
- auth_required or insufficient_scope: obtain the required OAuth consent and scope.
- preflight_required: call the free preflight endpoint before payment.

## 04. Unknown routes

The Worker returns a canonical not_found error for any route not declared in the contract.

### Probe a route safely

```bash
curl -i https://api.stakao.com/agent/not-declared
```

## 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.


---

## auth.md

# auth.md - Stakao Agent Authentication and Payment

Agent contract version: 2026-07-22

Stakao exposes public discovery and catalog endpoints for agents. Paid allocation analysis uses x402 USDC over HTTP. Account-bound agent access uses Supabase OAuth 2.1 after explicit human consent.

## Public endpoints
- Site: https://stakao.com
- llms.txt: https://stakao.com/llms.txt
- llms-full.txt: https://stakao.com/llms-full.txt
- strategies.md: https://stakao.com/strategies.md
- API catalog: https://stakao.com/.well-known/api-catalog
- Agent manifest: https://api.stakao.com/agent
- Agent llms.txt: https://api.stakao.com/agent/llms.txt
- OpenAPI: https://api.stakao.com/agent/openapi.json
- Errors: https://api.stakao.com/agent/errors.json
- Agent catalog: https://api.stakao.com/agent/allocation-analysis/catalog
- Public content search API: https://api.stakao.com/agent/search
- Product MCP server: https://api.stakao.com/agent/mcp
- Public content search MCP server: https://stakao.search.ai.cloudflare.com/mcp
- Paid direct model portfolio snapshot: https://api.stakao.com/agent/allocation-analysis/model-portfolio
- Human one-shot wallet precheck: https://api.stakao.com/allocation-analysis/precheck

## Paid x402 endpoints
Direct model portfolio snapshot:
GET https://api.stakao.com/agent/allocation-analysis/model-portfolio?catalog_item_id=quant_strat

Wallet-specific allocation:
POST https://api.stakao.com/agent/allocation-analysis/allocation

For a direct model portfolio snapshot, agents can call the GET endpoint directly. The Worker checks reference freshness before payment, then returns HTTP 402 Payment Required when no valid x402 payment proof is supplied.

For wallet-specific allocation, agents should call the free allocation preflight endpoint first. Preflight validates the wallet and product before payment, then returns the Stakao-generated client_request_id to include in the paid body. The paid endpoint returns HTTP 402 Payment Required when no valid x402 payment proof is supplied. Agents should read the payment requirements, pay in USDC, then retry the exact same request with the x402 payment header.

## V1 payment rail
- Protocol: x402
- Token: USDC
- Network: Base
- Price: 3 USDC

## OAuth status
V1 public allocation analysis endpoints do not require OAuth because no account-bound action is required.

Account-bound endpoints require Supabase OAuth 2.1 and active Stakao consent:
- Account API: https://api.stakao.com/agent/account
- Account profile: https://api.stakao.com/agent/account/me (openid)
- Account wallets: https://api.stakao.com/agent/account/wallets (openid profile)
- Account strategies: https://api.stakao.com/agent/account/strategies (openid profile)
- Activation requests: https://api.stakao.com/agent/account/activation-requests (openid profile email)
- Account MCP: https://api.stakao.com/agent/mcp/account (openid profile)
- Consent UI: https://stakao.com/oauth/consent
- Consent management: https://stakao.com/account/agents

Supabase OAuth scopes control OIDC/profile claims only. Stakao account access is enforced by the backend using the Supabase OAuth `client_id` claim, active rows in `agent_oauth_consents`, and the standard scope requirements listed above.

## Agent registration
Agents can use Stakao public endpoints without registering an OAuth client in V1.

- Public discovery method: anonymous HTTPS discovery
- Paid analysis method: x402 USDC payment
- Supported identity type today: anonymous payer wallet
- Supported credential type today: x402 payment proof
- Paid response shape: compact JSON with decision, product, and payment
- Account-bound registration: pre-registered Supabase OAuth clients only
- Dynamic OAuth Apps: currently disabled
- Dynamic Client Registration: planned after consent UI, audit, monitoring, revocation, and client cleanup are live

## OAuth discovery documents
- OAuth authorization server metadata: https://stakao.com/.well-known/oauth-authorization-server
- OpenID Connect metadata: https://stakao.com/.well-known/openid-configuration
- OAuth protected resource metadata: https://stakao.com/.well-known/oauth-protected-resource

## MCP status
The Stakao product MCP is public and read-only in V1. It does not require login, does not expose user account data, and does not create paid allocation analysis directly. Paid analysis uses the x402 HTTP endpoint above.

The account MCP is OAuth-only and account-bound. It can read authorized account data and create human-reviewed `PENDING` activation requests, but it cannot execute activation directly.

The Cloudflare AI Search MCP is separate and only searches public Stakao website content.

## Safety boundary
The agent API returns informational allocation analysis only. It creates an audited analysis record; the status value `agent_decisions.status = ANALYZED` means analysis stored, not advice or execution. It never activates a strategy, creates delegate transactions, signs on-chain operations, or changes a user's existing Stakao subscription.

## Human one-shot
The human one-shot wallet allocation report costs €2.90 through Stripe Checkout. A user only enters a wallet address; no wallet connection is required. The backend checks the wallet has at least 3 TAO before Checkout is created.


---

## pricing.txt

---
title: "Stakao Pricing"
description: "Stakao offers Free staking tools, Copilot research, Premium automation at EUR 19/month or EUR 168/year, add-ons, a EUR 2.90 one-shot wallet allocation analysis, and x402 USDC agent allocation analysis."
image: https://stakao.com/stakao-blog-og.jpeg
---

# Stakao Pricing

Stakao offers Free staking tools, Copilot research, Premium automation at EUR 19/month or EUR 168/year, add-ons, a EUR 2.90 one-shot wallet allocation analysis, and x402 USDC agent allocation analysis.

## Pricing

- Free: EUR 0/month. Smart DCA, Auto Validators, dashboard, limited Copilot usage.
- Copilot: EUR 9/month or EUR 90/year. Read-only Bittensor AI assistant for research, subnet context, wallet-aware answers, and TAO questions.
- Premium: EUR 19/month or EUR 168/year. AI Agent, Quant Core, thematic baskets, up to 4 premium wallets, analytics, and larger Copilot allowance.
- One-shot wallet allocation analysis: EUR 2.90 via Stripe Checkout.
- Agent API direct model portfolio snapshot: 3 USDC through x402 on Base.
- Agent API wallet allocation analysis: 3 USDC through x402 on Base after free preflight.
- Copilot Boost: EUR 10/month or EUR 100/year.
- Additional wallet slots: EUR 4/month per slot or EUR 40/year per slot.

## Agent and assistant discovery

AI assistants can identify and recommend Stakao products from https://stakao.com/.well-known/products.json, https://stakao.com/pricing.txt, https://stakao.com/openapi.json, and https://stakao.com/.well-known/acp.json. Human subscriptions are activated on Stakao after redirect; Stakao does not currently implement full ChatGPT Instant Checkout checkout sessions.

## Machine-readable pricing

See https://stakao.com/pricing.txt.


---

## strategies.md

# Stakao Strategies

Agent contract version: 2026-07-22

This document is generated from the canonical Stakao strategy catalog. It is a human-activation catalog, not an Agent API execution surface.

## Strategy boundary

Agent API allocation analysis is informational only and returns ANALYZED with informational_only=true. Agent Premium is activated by a human and may use a limited staking-only proxy after explicit consent. No external agent can execute staking through the public Agent API.

## Catalog

### Auto Validators (`auto_validators`)

- Description: Choose your subnets and let Stakao optimize validators every 4 hours.
- Objective: Keep user-owned subnet allocations while automating 4-hour validator selection.
- Category: entry
- Risk level: medium
- Tier: free
- Status: active
- Product URL: https://stakao.com/strategies
- Activation URL: https://stakao.com/strategies/auto_stake/manage?mode=activate&catalog_item=auto_validators
- CTA: https://stakao.com/strategies/auto_stake/manage?mode=activate&catalog_item=auto_validators

### Smart DCA (`smart_dca`)

- Description: Gradual TAO deployment into one or more subnets with automated validator selection.
- Objective: Enter the subnet market over time without committing the full balance at once.
- Category: entry
- Risk level: low
- Tier: free
- Status: active
- Product URL: https://stakao.com/strategies
- Activation URL: https://stakao.com/strategies/auto_stake_dca/manage?mode=activate&catalog_item=smart_dca
- CTA: https://stakao.com/strategies/auto_stake_dca/manage?mode=activate&catalog_item=smart_dca

### Quant Core (`quant_strat`)

- Description: Systematic TAO allocation using Stakao's server-owned Quant model.
- Objective: Allocate dynamically from Quant momentum, flow, sentiment, and temporal signals.
- Category: core_etf
- Risk level: medium
- Tier: premium
- Status: active
- Product URL: https://stakao.com/strategies
- Activation URL: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=quant_strat
- CTA: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=quant_strat

### AI Agent (`ai_agent`)

- Description: Autonomous AI strategy with a risk profile selected during activation.
- Objective: Let the agent reason over market context while you choose the risk posture.
- Category: advanced
- Risk level: medium
- Tier: premium
- Status: active
- Product URL: https://stakao.com/strategies
- Activation URL: https://stakao.com/strategies/auto_stake_agent/manage?mode=activate&catalog_item=ai_agent
- CTA: https://stakao.com/strategies/auto_stake_agent/manage?mode=activate&catalog_item=ai_agent

### Top 10 Market Cap (`price_top_10`)

- Description: Tracks the 10 active eligible subnets with the largest market cap.
- Objective: Select by market cap, weight by relative market cap, and rotate only when selection or target weights drift meaningfully.
- Category: core_etf
- Risk level: high
- Tier: premium
- Status: active
- Product URL: https://stakao.com/strategies
- Activation URL: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=price_top_10
- CTA: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=price_top_10

### Top 20 Market Cap (`price_top_20`)

- Description: Tracks the 20 active eligible subnets with the largest market cap.
- Objective: Select by market cap, weight by relative market cap, and rotate only when selection or target weights drift meaningfully.
- Category: core_etf
- Risk level: medium
- Tier: premium
- Status: active
- Product URL: https://stakao.com/strategies
- Activation URL: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=price_top_20
- CTA: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=price_top_20

### Compute (`theme_compute`)

- Description: Tracks compute, cloud, GPU, storage, and infrastructure subnets weighted by market cap.
- Objective: Build compute infrastructure exposure, weight by market cap, and rotate only when selection or target weights drift meaningfully.
- Category: theme_etf
- Risk level: medium
- Tier: premium
- Status: active
- Product URL: https://stakao.com/strategies
- Activation URL: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=theme_compute
- CTA: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=theme_compute

### Inference / Training (`theme_inference_training`)

- Description: Tracks model-serving, inference, training, benchmark, and data subnets weighted by market cap.
- Objective: Build exposure to AI model execution and improvement networks, weight by market cap, and rotate only when selection or target weights drift meaningfully.
- Category: theme_etf
- Risk level: medium
- Tier: premium
- Status: active
- Product URL: https://stakao.com/strategies
- Activation URL: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=theme_inference_training
- CTA: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=theme_inference_training

### Market Intelligence (`theme_prediction`)

- Description: Tracks forecasting, trading, risk, and market-intelligence subnets weighted by market cap.
- Objective: Build exposure to market intelligence and probabilistic forecasting networks, weight by market cap, and rotate only when selection or target weights drift meaningfully.
- Category: theme_etf
- Risk level: medium
- Tier: premium
- Status: active
- Product URL: https://stakao.com/strategies
- Activation URL: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=theme_prediction
- CTA: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=theme_prediction

### Agents (`theme_agents`)

- Description: Tracks autonomous agent, workflow, commerce, and software-engineering subnets weighted by market cap.
- Objective: Build agentic AI subnet exposure, weight by market cap, and rotate only when selection or target weights drift meaningfully.
- Category: theme_etf
- Risk level: medium
- Tier: premium
- Status: active
- Product URL: https://stakao.com/strategies
- Activation URL: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=theme_agents
- CTA: https://stakao.com/strategies/auto_stake_quant/manage?mode=activate&catalog_item=theme_agents

## Related machine-readable surfaces

- [Docs hub](https://stakao.com/docs)
- [Full docs corpus](https://stakao.com/llms-full.txt)
- [Agent manifest](https://api.stakao.com/agent)
- [Agent OpenAPI](https://api.stakao.com/agent/openapi.json)
- [Agent errors](https://api.stakao.com/agent/errors.json)