> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useotto.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# API schemas and examples

> Find a route's current inputs, declared output and payment requirement without relying on copied sample data.

Use the running API's discovery documents when building a request. This keeps new routes, changed inputs and prices in one place.

| Interface   | Complete request reference                                              | Additional discovery                                                                                                              |
| ----------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| HTTP API    | [OpenAPI](https://x402.ottoai.services/openapi.json)                    | [Agent catalog](https://x402.ottoai.services/llm.txt), [x402 discovery](https://x402.ottoai.services/.well-known/x402)            |
| X Layer API | [OpenAPI](https://xlayer.ottoai.services/openapi.json)                  | [Agent catalog](https://xlayer.ottoai.services/llm.txt), [protocol allowlist](https://xlayer.ottoai.services/supported-protocols) |
| MCP         | `tools/list` on [Otto Intel MCP](/acp-swarm/otto-intel-mcp)             | Full JSON schema and description for every tool                                                                                   |
| ACP         | `offerings[].requirements` in [`acp browse --json`](/acp-swarm/acp-cli) | Match the active provider wallet and store first                                                                                  |

## Inspect an HTTP request

These reads are free. They need `curl` and `jq`, but no wallet:

```bash theme={null}
curl -s https://x402.ottoai.services/openapi.json \
  | jq '.paths["/equity-intel"]'

curl -s 'https://x402.ottoai.services/service-detail?path=/equity-intel'

curl -s https://xlayer.ottoai.services/openapi.json \
  | jq '.paths["/auto-defi-withdraw"].post.requestBody'
```

Check the method, required query or body fields, enum values, amount units and any additional authorization. For example, an Otto X withdrawal needs a position `ratio` or an `amount`; a price listing alone does not describe that execution contract.

## LP pool APR

This unpaid request asks for the exact SPY/MU v4 pool on Robinhood Chain. It
returns the payment challenge for a **0.001 USDC** Base payment. Keep the same
JSON body when repeating it with your payment authorization:

```bash theme={null}
curl -i https://x402.ottoai.services/lp-pool-apr \
  -H 'Content-Type: application/json' \
  --data '{"chainId":4663,"protocol":"uniswap-v4","poolId":"0xcc2a903a8744a65258bb07fbeea553a25410f731c9fef306321d0c176a09542c","token0":"0x117cc2133c37b721f49de2a7a74833232b3b4c0c","token1":"0xff080c8ce2e5feadaca0da81314ae59d232d4afd","hook":"0x0000000000000000000000000000000000000000"}'
```

The chain, protocol, pool, ordered token addresses and hook must match the
provider response. A v3 pool uses its 20-byte pool address and a zero hook; a v4
pool uses its 32-byte PoolId. Exact identity validation does not establish pool
safety or investment suitability.

Read `feeAprPct`, `incentiveAprPct` and `totalAprPct` with `status`, `retrievedAt`,
`validUntil`, `source` and `components`. Valid cached numbers remain current for
an hour. Failed refreshes keep last-good numbers with their original age and a
stale label. Zero incentives means the provider explicitly reported none;
`null` means that component has no available observation.

For position context, inspect the `POST /lp-intelligence` schema and supply a
`position` containing `chainId`, `positionManager` and `tokenId`. It costs
**0.02 USDC on Base**. Pool APR appears in `advice.details.yield`; current position
reads, conditional models and recorded history retain their separate evidence.
The [HTTP guide](/acp-swarm/x402#read-lp-rates-and-position-context) explains how
to interpret the rates.

## Inspect the payment and declared output

An unpaid request to a paid route returns a `402` challenge. Decode its `PAYMENT-REQUIRED` header:

```bash theme={null}
curl -sD - -o /dev/null \
  'https://x402.ottoai.services/equity-intel?ticker=NVDA' \
  | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' \
  | base64 -d \
  | jq '{resource, accepts, bazaar: .extensions.bazaar}'
```

`accepts` supplies the price, network, token and recipient for that call. Where advertised, `extensions.bazaar` supplies the declared output schema and example. An example explains a shape; its prices, scores and dates are not current market observations. A successful paid call returns the actual result.

A `402` does not prove your input is valid: some routes evaluate payment before parameter validation. Read the request schema first. Missing fields, `null`, zero and a measured value can have different meanings; preserve the response's coverage and caveats. The [HTTP guide](/acp-swarm/x402#read-the-result) explains freshness metadata.

For a paid request, follow [HTTP API](/acp-swarm/x402) or [X Layer API](/acp-swarm/otto-x). Compare the returned body with the requested service and retain its payment receipt.