# RWABento — Agent Skill

> Messy assets. Clean data. One normalized API for tokenized stocks and real-world assets on Robinhood Chain (chain id `4663`).

This page is written for AI agents (Claude Code, Codex, Cursor, and anything MCP-capable) and the humans wiring them up. Save it as a skill, or just point your agent at the MCP endpoint below.

## Fastest path: MCP (no wallet needed)

RWABento ships a native MCP server over Streamable HTTP. Agents get full read access through it — the wallet gate applies to the human REST/browser surfaces, not to MCP.

**Claude Code**

```bash
claude mcp add --transport http rwabento https://api.rwabento.xyz/mcp
```

**Any MCP client (JSON config)**

```json
{
  "mcpServers": {
    "rwabento": {
      "type": "http",
      "url": "https://api.rwabento.xyz/mcp"
    }
  }
}
```

**Local development**: replace the URL with `http://localhost:8787/mcp`.

### MCP tools

| Tool | Arguments | Returns |
|---|---|---|
| `list_assets` | `type?` (`equity`\|`etf`), `limit?`, `cursor?` | Paginated normalized asset records |
| `get_asset` | `address`, `include_provenance?` | Full four-compartment record for one contract |
| `get_compartment` | `address`, `compartment` (`identity`\|`market`\|`liquidity`\|`rights`) | One compartment only |
| `get_coverage` | — | Honest index counters and completeness |
| `get_sources_status` | — | Health of each upstream source |

## Data model (read this before interpreting results)

Every asset is one object with four compartments:

- **identity** — what the token is: symbol, name, issuer, canonical status, underlying instrument.
- **market** — price, market cap, volume, holders, staleness.
- **liquidity** — venues, depth, liquidity state.
- **rights** — what holding actually grants: `holder_claim: "economic_exposure"` means exposure, not ownership of the underlying security.

Honesty rules the schema:

- `null` / `"unknown"` are **valid values**. The API never invents certainty. Do not treat `unknown` as an error; report it as unknown.
- With `include_provenance`, every field becomes an envelope: `{ value, source_type, source_url, observed_at, block_number, confidence }`. Cite `source_url` when provenance matters.
- `confidence` describes source certainty, never asset quality.
- Assets are identified by `{chain_id}/{contract_address}`. **Tickers are never identifiers** — unrelated contracts can copy a symbol.

## REST API (wallet-gated)

The REST surface `https://api.rwabento.xyz/v1` requires a wallet session for `/v1/assets*`. Soon this gate will also require holding the RWABento token (launching on Virtuals). If your agent controls a wallet, the flow is three calls:

```
POST /v1/auth/nonce   {"address": "0x…"}          → { nonce, message }
  — sign `message` with personal_sign —
POST /v1/auth/verify  {"address", "nonce", "signature"} → { token, expires_at }
GET  /v1/assets/4663/0x…  with  Authorization: Bearer <token>
```

Open (no wallet) REST endpoints:

| Endpoint | Purpose |
|---|---|
| `GET /v1/health` | Liveness + schema version |
| `GET /v1/coverage` | Index counters, never decorative |
| `GET /v1/sources/status` | Upstream source health |
| `GET /v1/auth/gate` | Current gate mode (signature-only vs signature+holding) |

Errors follow one model — `{ error: { code, message, request_id } }` with codes `INVALID_ADDRESS`, `UNSUPPORTED_CHAIN`, `ASSET_NOT_FOUND`, `SOURCE_UNAVAILABLE`, `RATE_LIMITED`, `UNAUTHORIZED`, `HOLDING_REQUIRED`, `INTERNAL_ERROR`.

Rate limits: a per-IP burst guard of 300 requests/minute. Back off on `429`; the window resets within 60 seconds.

## Canonical example (AAPL Stock Token)

```
address:  0xaF3D76f1834A1d425780943C99Ea8A608f8a93f9
chain_id: 4663
```

MCP: `get_asset {"address": "0xaF3D76f1834A1d425780943C99Ea8A608f8a93f9"}`

## Ground rules for agents

1. Prefer MCP tools over scraping the website.
2. Never present `unknown` fields as facts, and never fill them with guesses.
3. Quote `observed_at` alongside any price you surface; prices without timestamps are meaningless.
4. This is informational data, not investment advice and not a settlement-grade oracle. Verify contract addresses against primary sources before anything irreversible.

---

RWABento is an independent data interface and is not affiliated with or endorsed by Robinhood.