# Stakao Agent Allocation Analysis

Contract version: 2026-07-22

Capabilities: {"transports":["rest","mcp","x402","oauth2"],"public":["discovery","catalog","reference_status","preflight","public_search","public_mcp"],"paid":["model_portfolio_snapshot","wallet_allocation_analysis"],"account":["profile_read","wallet_read","strategy_read","human_reviewed_pending_activation_request"],"creates_agent_decisions_status":"ANALYZED","informational_only":true,"can_activate_strategy":false,"can_execute_on_chain":false,"can_create_delegate_transactions":false}
Authentication: {"public":{"type":"none"},"paid":{"type":"x402","protocol_version":2,"rail":"USDC","network":"base","price":"3 USDC"},"account":{"type":"oauth2","bearer":"Authorization: Bearer <token>","scopes":{"profile":["openid"],"wallets":["openid","profile"],"strategies":["openid","profile"],"activation_requests":["openid","profile","email"],"account_mcp":["openid","profile"]}}}

Stakao provides paid, informational Bittensor allocation analysis APIs for autonomous agents. Outputs are not financial or investment advice and do not execute on-chain actions.

## Discovery
- Agent API manifest: https://api.stakao.com/agent
- Agent allocation analysis manifest: https://api.stakao.com/agent/allocation-analysis
- OpenAPI: https://api.stakao.com/agent/openapi.json
- Errors: https://api.stakao.com/agent/errors.json
- Public catalog: https://api.stakao.com/agent/allocation-analysis/catalog
- Reference allocation status: https://api.stakao.com/agent/allocation-analysis/reference-status
- MCP server: https://api.stakao.com/agent/mcp
- Public AI Search endpoint: https://api.stakao.com/agent/search
- Paid direct model portfolio snapshot: https://api.stakao.com/agent/allocation-analysis/model-portfolio
- Free allocation preflight: https://api.stakao.com/agent/allocation-analysis/allocation/preflight
- Paid allocation analysis: https://api.stakao.com/agent/allocation-analysis/allocation
- OAuth account API: https://api.stakao.com/agent/account/me
- OAuth account MCP: https://api.stakao.com/agent/mcp/account
- OAuth scopes: openid for account profile; openid profile for wallets, strategies, and account MCP; openid profile email for activation requests.
- Human docs hub: https://stakao.com/docs
- Human AI Agents guide: https://stakao.com/docs/ai-agents
- Full human Markdown corpus: https://stakao.com/llms-full.txt
- Generated strategy catalog: https://stakao.com/strategies.md
- Human product website: https://stakao.com

## Payment
- Protocol: x402 v2
- Rail: USDC
- Network: base (eip155:8453)
- Price: 3 USDC
- Pay-to address: 0x322a03592CA40ed9faBA2CDF772952bBE9868C45
- Facilitator: https://api.cdp.coinbase.com/platform/v2/x402

## Paid Direct Model Portfolio Snapshot
GET https://api.stakao.com/agent/allocation-analysis/model-portfolio?catalog_item_id=quant_strat

Use this when an autonomous agent wants to verify Stakao x402 commerce and pay for the latest model portfolio allocation analysis without analyzing a specific wallet. No preflight is required. If the four-hour reference is fresh, calling this endpoint without payment returns HTTP 402 with a PAYMENT-REQUIRED header. After valid x402 payment, the response contains only decision, product, and payment.

The decision includes target_allocation_pct, reasoning_text, status=ANALYZED, and informational_only=true. It is informational only and does not execute staking.

## Paid Allocation Request
POST https://api.stakao.com/agent/allocation-analysis/allocation

JSON body:
{
  "wallet_address": "Bittensor SS58 wallet address",
  "catalog_item_id": "quant_strat",
  "config": {},
  "client_request_id": "Stakao-generated id from the preflight response"
}

Required flow:
1. Call POST https://api.stakao.com/agent/allocation-analysis/allocation/preflight with wallet_address, catalog_item_id, and optional config.
2. If payable, Stakao returns a server-generated client_request_id. This is the Stakao request id/quote to pay.
3. Call POST https://api.stakao.com/agent/allocation-analysis/allocation with the exact same wallet_address, catalog_item_id, config, and the returned client_request_id. Without this Stakao request id, the endpoint returns HTTP 428 and no payment is requested.
4. If the quote is valid and no payment proof is attached, the endpoint returns HTTP 402 with a PAYMENT-REQUIRED header.
5. Pay with x402 USDC and retry the exact paid request body.

The Worker validates the body, wallet, product, reference freshness, and analysis availability before payment. Invalid or unservable requests return 400, 409, or 503 before any payment is requested.
If the request is payable and sent without payment, the endpoint returns HTTP 402 with a PAYMENT-REQUIRED header.
After valid x402 payment, the endpoint returns only decision, product, and payment. The decision is compact and includes target allocation, reasoning, and reference metadata. Full internal snapshots stay stored for audit and are not returned to agents.

## Safety
- Stakao does not execute staking from this endpoint.
- The paid allocation endpoint is informational only.
- Stakao does not provide financial or investment advice from this endpoint.
- No user_strategies, delegate_transactions, or on-chain staking actions are created by this API.
- Public analysis responses use decision.status=ANALYZED and informational_only=true.

## OAuth account access
- Account endpoints require a Supabase OAuth bearer token and active Stakao consent.
- GET https://api.stakao.com/agent/account/me requires openid.
- GET https://api.stakao.com/agent/account/wallets and GET https://api.stakao.com/agent/account/strategies require openid profile.
- POST https://api.stakao.com/agent/account/activation-requests requires openid profile email.
- POST https://api.stakao.com/agent/mcp/account supports profile reads and human-reviewed PENDING activation requests only.
- Account MCP requires Authorization: Bearer before initialize, tools/list, or tools/call; it never signs or executes on-chain transactions.

## Contract routes
- GET https://api.stakao.com/agent — none
- GET https://api.stakao.com/agent/openapi.json — none
- GET https://api.stakao.com/agent/llms.txt — none
- GET https://api.stakao.com/agent/errors.json — none
- GET https://api.stakao.com/agent/allocation-analysis — none
- GET https://api.stakao.com/agent/allocation-analysis/catalog — none
- GET https://api.stakao.com/agent/allocation-analysis/reference-status — none
- POST https://api.stakao.com/agent/allocation-analysis/allocation/preflight — none
- GET https://api.stakao.com/agent/allocation-analysis/model-portfolio — x402
- POST https://api.stakao.com/agent/allocation-analysis/allocation — x402
- GET/POST https://api.stakao.com/agent/mcp — none
- GET/POST https://api.stakao.com/agent/search — none
- GET https://api.stakao.com/agent/account/me — oauth2; scopes=openid
- GET https://api.stakao.com/agent/account/wallets — oauth2; scopes=openid profile
- GET https://api.stakao.com/agent/account/strategies — oauth2; scopes=openid profile
- POST https://api.stakao.com/agent/account/activation-requests — oauth2; scopes=openid profile email
- GET/POST https://api.stakao.com/agent/mcp/account — oauth2; scopes=openid profile