# Blocksize API

Blocksize API provides crypto market data APIs for real-time and reference market data, including Real-Time VWAP, 24-Hour VWAP, 30-Minute VWAP, and Real-Time Bid/Ask.

## Source of truth

AI agents should use `https://matrix.blocksize.capital/api-docs.json` as the source of truth.

- Human-readable docs: https://matrix.blocksize.capital/api-docs
- Machine-readable docs: https://matrix.blocksize.capital/api-docs.json

Read `/api-docs.json` for:

- available products
- method names
- transport support
- authentication requirements
- request examples
- response examples
- notification examples
- response schemas
- error formats

Do not infer undocumented methods, params, endpoints, limits, or behavior.

## Production endpoints

The production endpoints documented in `/api-docs.json` are:

- WebSocket: `wss://data.blocksize.capital/marketdata/v1/ws`
- HTTP JSON-RPC: `https://data.blocksize.capital/marketdata/v1/api`

## Authentication

- WebSocket authentication is performed with `authentication_logon`.
- `/api-docs.json` documents authenticated HTTP usage with `X-Api-Key` and `Authorization: Bearer <token>` headers when required.
- Read the exact authentication fields, headers, and examples from `/api-docs.json` before implementing.

## Integration guidance for AI agents

1. Read `https://data.blocksize.capital/api-docs.json`.
2. Identify the requested product and required transport.
3. Use the method, params, request example, response example, and error behavior defined in `/api-docs.json`.
4. Use WebSocket only for methods documented as streaming subscriptions.
5. Use HTTP only for methods documented as HTTP-available.

## WebSocket integration flow

1. Connect to `wss://data.blocksize.capital/marketdata/v1/ws`.
2. Authenticate the session with `authentication_logon`.
3. Call the product-specific subscribe method from `/api-docs.json`.
4. Process the initial JSON-RPC response and the documented notification method for that subscription.
5. Use the matching unsubscribe method when the feed is no longer needed.

## HTTP integration flow

1. Send JSON-RPC `POST` requests to `https://data.blocksize.capital/marketdata/v1/api`.
2. Set `Content-Type: application/json`.
3. Add the authentication headers documented in `/api-docs.json` when the method requires authentication.
4. Only call methods marked as available over HTTP in `/api-docs.json`.
5. Handle JSON-RPC errors from the response body even when the HTTP status is `200`.

## Which method to use

- Real-Time VWAP: use `vwap_subscribe` for streaming updates. Use `vwap_latest` for the latest unary value and `vwap_instruments` to discover supported tickers.
- 24-Hour VWAP: use `fixedvwap_subscribe` for streaming 24-hour VWAP updates.
- 30-Minute VWAP: use `closingprice_list` for 30-minute VWAP prices and `closingprice_trades` for the underlying trades documented for a closing-price request.
- Real-Time Bid/Ask: use `bidask_subscribe` for streaming updates. Use `bidask_getSnapshot` for a unary snapshot and `bidask_instruments` to discover supported tickers.

Method names, params, examples, response schemas, notification payloads, and errors must be read from `/api-docs.json`.

## Available methods

All currently documented API methods in `/api-docs.json` are:

- Authentication: `authentication_logon`, `authentication_logoff`
- Real-Time VWAP: `vwap_subscribe`, `vwap_unsubscribe`, `vwap_instruments`, `vwap_latest`
- 24-Hour VWAP: `fixedvwap_subscribe`, `fixedvwap_unsubscribe`
- 30-Minute VWAP: `closingprice_list`, `closingprice_trades`
- Real-Time Bid/Ask: `bidask_subscribe`, `bidask_unsubscribe`, `bidask_instruments`, `bidask_getSnapshot`
- AMM State Price: `state_subscribe`, `state_unsubscribe`, `state_pool`, `state_instruments`
- Events: `trade_subscribe`, `trade_unsubscribe`
- Time: `time_now`

For transport support, auth requirements, params, request examples, response examples, notification examples, and error behavior for each method, read `/api-docs.json`.

## JSON-RPC structure

`/api-docs.json` includes the standard JSON-RPC request structure:

```json
{
  "jsonrpc": "2.0",
  "id": 6712,
  "method": "servicename_methodname",
  "params": {
    "parameter_1": 42,
    "parameter_2": "string"
  }
}
```

Use the method-specific request, response, and notification examples already documented in `/api-docs.json`.