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