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