API documentation

One normalized asset object, four compartments, provenance on demand. Base URL in production: https://api.rwabento.xyz/v1. Local: /v1.

Quick start

Two doors. Humans connect a wallet on Robinhood Chain mainnet; agents connect over MCP with zero setup.

# agents (Claude Code)
claude mcp add --transport http rwabento https://api.rwabento.xyz/mcp

# humans: open /explorer.html and press "Connect Wallet"

Fields without a verified source return null or "unknown". The schema never invents certainty.

Access: connect your wallet

Asset data (/v1/assets*) requires a wallet session on Robinhood Chain mainnet (4663). You sign one gasless message that proves wallet ownership. No funds move and no permissions are granted. Soon: when the RWABento token launches on Virtuals, the same step will also require a minimum holding; check GET /v1/auth/gate for the live gate mode.

POST /v1/auth/nonce   {"address":"0x…"}            → { nonce, message }
# sign `message` with personal_sign, then
POST /v1/auth/verify  {"address","nonce","signature"} → { token, expires_at }

curl /v1/assets -H "Authorization: Bearer <token>"

Sessions last 24 hours. In the browser, the Connect Wallet button on the Explorer and Asset pages runs this whole flow for you. /v1/health, /v1/coverage, and /v1/sources/status stay public.

Agents & MCP

RWABento ships a native MCP server (Streamable HTTP) at /mcp with five tools: list_assets, get_asset, get_compartment, get_coverage, get_sources_status. MCP is the agent-native door; it does not require a wallet.

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

Full agent instructions, data-honesty rules, and the wallet flow for agent-controlled wallets live at /skills.md.

Asset identifiers

The canonical key is {chain_id}/{contract_address}. Robinhood Chain mainnet is 4663. Tickers are never identifiers; unrelated contracts can copy a symbol.

Endpoints

EndpointReturns
GET /assetsPaginated list. Filters: type, canonical_status, limit, cursor.
GET /assets/{chain}/{address}Full four-compartment record.
GET /assets/{chain}/{address}/identityIdentity compartment only. Same for /market, /liquidity, /rights.
GET /assets/{chain}/{address}/provenanceEvery field in full envelope form.
GET /coverageIndexed counts and per-compartment completeness. Never decorative.
GET /sources/statusHealth of each upstream source.
GET /healthLiveness and schema version.
GET /auth/gateCurrent gate mode: signature-only, or signature plus token holding.
POST /auth/nonceSign-in nonce and message for a wallet address.
POST /auth/verifyVerify the signature; returns a 24-hour Bearer token.
GET /auth/sessionInspect the current session (Bearer header).
POST /mcpMCP Streamable HTTP endpoint for agents.

Provenance model

Add ?include=provenance to any asset endpoint and each field becomes an evidence envelope:

{
  "value": "official",
  "source_type": "robinhood_docs",
  "source_url": "https://docs.robinhood.com/chain/contracts/",
  "observed_at": "2026-07-17T00:00:00Z",
  "block_number": null,
  "confidence": "high"
}

Source hierarchy: chain state → official registry → explorer metadata → issuer documents → venues/oracles → derived calculations. Confidence describes source certainty, never asset quality.

Freshness and confidence

Time-sensitive objects carry observed_at, block_number, and a staleness state (live, recent, stale, unknown). Confidence levels: high (canonical chain state or first-party publication), medium (reputable timestamped provider), low (derived), unknown.

Rate limits

There are no tiers. A per-IP burst guard of 300 requests per minute exists only to stop runaway loops; normal use never reaches it, and the window resets within 60 seconds. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Read endpoints send Cache-Control headers, so responses cache cleanly behind any CDN or proxy.

Errors

{
  "error": {
    "code": "ASSET_NOT_FOUND",
    "message": "No indexed asset matches this chain and contract address.",
    "request_id": "req_7eb92365"
  }
}

Codes: INVALID_ADDRESS, UNSUPPORTED_CHAIN, ASSET_NOT_FOUND, SOURCE_UNAVAILABLE, RATE_LIMITED, UNAUTHORIZED, HOLDING_REQUIRED, INTERNAL_ERROR.

Changelog

DateChange
2026-07-19Wallet gate: asset data requires a signed wallet session on chain 4663 (token-holding requirement reserved for the Virtuals launch). Native MCP server at /mcp and agent skill at /skills.md.
2026-07-19API keys removed; per-IP burst guard; cacheable responses.
2026-07-18v1 public preview: assets, compartments, provenance, coverage, sources.