# Agent-Native Middleware API — LLM-Readable Documentation

**Agent-first:** You are the intended reader. This file is primary prose for autonomous agents and orchestrators. Before acting, fetch `GET /.well-known/agent.json` and use `GET /health/dependencies` (`simulation_modes`, `enable_proof_surfaces`) so you do not treat simulated domains as real.

**Version:** use `version` from `GET /.well-known/agent.json` (this document may be cached).
**Base URL:** https://api-service-production-433c.up.railway.app
**Auth:** `X-API-Key` header on protected routes

---

## What This API Does

Agent Middleware API is a **governed MCP trust plane** for autonomous agents:
scoped permits, metered tool invocation, signed receipts, and wallet audit chains.

The product loop is:

```text
discover -> authenticate -> authorize -> invoke -> meter -> receipt -> audit -> govern
```

Read `capabilities` on `GET /.well-known/agent.json` for the product wedge.
Entries under `proof_surfaces` are labeled scaffolding — often simulated, and not
mounted when `enable_proof_surfaces` is false.

Core infrastructure:
- **Identity & authority** — Wallet-scoped agents, API keys, signing keys, KYC hooks
- **Discovery** — MCP tools, `.well-known/agent.json`, `llms.txt`, OpenAPI, `/v1/discover`
- **Execution governance** — Permit-gated MCP invocation, receipts, audit chain
- **Economics** — Wallet budgets, ledger charges, idempotent replay without double-charge
- **Readiness** — `/health/dependencies` (`simulation_modes`, `enable_proof_surfaces`)

---

## Quick Start for Agents

### 1. Discover What This API Offers

```bash
GET /.well-known/agent.json
GET /llms.txt
GET /mcp/tools.json
GET /openapi.json
```

`GET /llm.txt` remains available as a backward-compatible alias.

Use `/v1/discover` as an optional expanded catalog after the bootstrap sequence.
Treat `/mcp/tools.json` as authoritative for callable MCP tools.
Before invoking, inspect the `/health/dependencies` JSON body: HTTP 200 alone
does not mean every dependency is ready. Health never replaces authentication,
permit authorization, or receipt verification.

### 2. Get Operator-Provisioned Access

There is no public signup or unauthenticated key mint. The operator provisions
the sponsor/partner wallet, wallet-scoped API key, credits, and permit. Pass the
key as `X-API-Key: your-key` on every protected request.

### 4. Governed Tool Loop (dogfood)

Register one real tool (ops/scripts; local dogfood uses `partner.notes.write`),
then:

```bash
# Issue a scoped permit for that tool
POST /v1/permits
{"wallet_id": "...", "allowed_tools": ["partner.notes.write"], ...}

# Invoke via MCP with permit + idempotency key
POST /mcp/messages
{"jsonrpc":"2.0","method":"tools/call","params":{...}}

# Verify the signed receipt
GET /v1/receipts/{receipt_id}
```

Do **not** start with telemetry, agent comms, or AI decide/heal endpoints —
those are proof surfaces, not the wedge.

---

## MCP Tool Discovery

```bash
# List available tools (ops-registered / dogfood only when proof surfaces are off)
GET /mcp/tools.json

# Call a tool via MCP
POST /mcp/messages
{"jsonrpc": "2.0", "method": "tools/list", "id": 1}
```

Phase9 AWI / marketplace preview stubs (`awi_*`, `data-indexer`, etc.) are
**not** advertised when `ENABLE_PROOF_SURFACES=false`.

---

## Billing & Pricing

### Credit System
- Credits are a closed-loop metering unit for the pilot, not payment rails.
- There is no public pricing tier, free-credit grant, SLA, or settlement claim.
- Operators provision partner credits; public self-serve top-up is out of scope.

### Rate Limits
- 120 requests/minute per API key
- Burst allowance: 20 extra

### Velocity Monitoring
Wallets are auto-frozen if spending exceeds:
- 1000 credits/hour
- 10000 credits/day

---

## SDKs

Prefer the HTTP trust loop above (permits → MCP invoke → receipts). Client
libraries are optional and not required for the wedge.

### Python 0.4.0 (release artifact only)

CI builds a wheel and sdist and attaches them to the
`python-sdk-v0.4.0` GitHub release. It is **not** published to PyPI. Install a
downloaded wheel, or install from a clone for development:

```bash
pip install ./b2a_sdk-0.4.0-py3-none-any.whl
pip install -e ./b2a_sdk
```

```python
from b2a_sdk import AgentMiddlewareClient

async with AgentMiddlewareClient(api_key="...", base_url="...") as client:
    tools = await client.discover_tools()
    result = await client.invoke_tool(
        tools[0].name,
        {"input": "..."},
        wallet_id="...",
        permit_id="...",
        idempotency_key="caller-owned-key",
    )
```

### TypeScript

No published TypeScript SDK. Use HTTP (`/mcp`, `/v1/permits`, `/v1/receipts`).

---

## Endpoints Summary

| Category | Prefix | Auth |
|----------|--------|------|
| Discovery | `/v1/discover` | Optional |
| Billing | `/v1/billing` | Required |
| Permits | `/v1/permits` | Required |
| Receipts | `/v1/receipts` | Required |
| Audit | `/v1/audit` | Required |
| MCP | `/mcp` | Optional |
| Health | `/health` | None |

Proof-surface prefixes (`/v1/awi`, `/v1/telemetry`, `/v1/comms`, `/v1/ai`, …)
are mounted only when `ENABLE_PROOF_SURFACES=true`.

---

## Error Codes

| Code | Meaning |
|------|---------|
| 401 | Missing or invalid API key |
| 403 | Access denied (cross-tenant) |
| 402 | Insufficient credits |
| 429 | Rate limit exceeded |
| 500 | Internal error |

---

## For More Information

- API Docs: `/docs`
- OpenAPI Spec: `/openapi.json`
- Wedge: `/WEDGE.md`
- Security limitations: `/SECURITY_LIMITATIONS.md`
- GitHub: https://github.com/PetrefiedThunder/agent-middleware-api