# BlockMind Agent API

Base URL: /api/agent
Format: JSON

Authentication:
- Send `Authorization: Bearer <agent_api_key>`
- If both cookie auth and bearer auth are present, bearer auth takes precedence.

Response envelopes:
- Success: `{ data, meta: { requestId, timestamp, asOf, pagination? } }`
- Error: `{ error: { code, message, hint, param?, nextActions, retryable }, meta: { requestId, timestamp } }`

Cursor pagination:
- Supported on list operations.
- Request params: `limit`, `cursor`
- Cursor is opaque base64url JSON: `{ id, sortValue }`
- Response meta: `pagination: { cursor, hasMore, count }`

Scopes:
- `portfolio:read` — portfolio_list, portfolio_get, positions_list, portfolio_snapshot
- `watchlist:read` — watchlists_list, watchlist_items_list
- `watchlists:write` — watchlist_create, watchlist_update, watchlist_delete, watchlist_item_create, watchlist_item_update, watchlist_item_delete
- `market:read` — market_prices, market_indicators, market_funding_rates, market_open_interest, market_social_sentiment, market_social_narrative, market_social_topic, market_social_timeseries, market_stock_quote, market_stock_fundamentals, market_instrument_search, market_instrument_quote, market_fund_profile, chains_list, assets_search, asset_resolve
- `reports:read` — reports_status
- `reports:write` — reports_generate
- `signals:write` — signal_create
- `workspace:write` — events_create, custom_capability_save
- (no scope required) — capabilities, audit_list, key_rotate, key_revoke

Plan gates:
- These endpoints describe technical capability. Agents must obey injected plan context. When plan=free, do not use market_stock_quote, market_stock_fundamentals, market_instrument_search, market_instrument_quote, market_fund_profile, or custom_capability_save.

Key management:
- `key_rotate` — Create a new key inheriting permissions. Old key stays active for zero-downtime rotation.
- `key_revoke` — Instant kill switch. Omit keyId to revoke the calling key itself.

Reports:
- `reports_generate` — Async report generation with idempotency key support.
- `reports_status` — Poll report generation status.

Signals:
- `signal_create` — Create a workspace-scoped signal with optional deduplication.

Available operations:
- portfolio_list
- portfolio_get
- positions_list
- events_create
- custom_capability_save
- watchlists_list
- watchlist_create
- watchlist_update
- watchlist_delete
- watchlist_items_list
- watchlist_item_create
- watchlist_item_update
- watchlist_item_delete
- portfolio_snapshot
- market_prices
- market_indicators
- market_funding_rates
- market_open_interest
- market_social_sentiment
- market_social_narrative
- market_social_topic
- market_social_timeseries
- market_stock_quote
- market_stock_fundamentals
- market_instrument_search
- market_instrument_quote
- market_fund_profile
- chains_list
- assets_search
- asset_resolve
- capabilities
- audit_list
- key_rotate
- key_revoke
- signal_create
- reports_generate
- reports_status

Quick usage:
1. Call `capabilities` to see your key permissions and rate limits.
2. Call `portfolio_list` to enumerate portfolios.
3. Use `positions_list` with portfolio filters and pagination.
4. Use `asset_resolve` for cross-chain symbol/name/address resolution.
5. Use `market_stock_quote` to read the latest stock quote by ticker symbol; the API refreshes stale cached snapshots when needed. For this stock endpoint, `percentChange24h` is day change from previous close and `volume24h` is current trading-day volume, not crypto rolling-24h semantics.
6. Use `market_stock_fundamentals` for a live Yahoo fetch-only fundamentals snapshot. Provide `symbol` and optional curated `sections`: profile, valuation, profitability, balanceSheet, earnings, filings.
7. Use `market_instrument_search`, `market_instrument_quote`, and `market_fund_profile` for non-stock instruments — ETFs, mutual funds, indexes (^GSPC), and commodity futures (GC=F). FX and options are not supported through these endpoints; CoinGecko remains canonical for crypto. `market_fund_profile` only accepts ETF and mutual fund symbols and exposes curated `sections`: profile, holdings, performance, fees, summary.
8. Use `market_social_narrative`, `market_social_topic`, and `market_social_timeseries` for live LunarCrush narrative, topic, and historical context.
9. Use `reports_generate` with an idempotency key for safe retries.
10. Use `signal_create` to report bugs, friction, or feature gaps to the workspace.
11. Use `error.hint`, `error.param`, and `error.nextActions` together to recover from failures.