BULK Provider

BULK is a public market-data provider in Market Lab and the planned execution venue. Public market data does not require an API key or agent wallet.

Current Scope

Market catalog:

• an embedded snapshot of BULK markets and trading rules
• offline market lookup through mlab markets
• deterministic mapping between BULK venue symbols and Market Lab symbols
• snapshot provenance through its source URL and fetch time

Market data:

• historical and live candles
• current and live orderbooks
• current and live open interest
• historical and live volume bars
• live volume delta derived from BULK trades
• exchange and market statistics
• current and live funding rates

Agent wallet:

• generate an agent wallet locally
• authorize the agent for a BULK account
• store the agent credential in the operating system keychain
• inspect registration status
• retry an unconfirmed registration without generating another agent
• revoke and remove an active agent

Market Lab cannot place, modify, or cancel BULK orders yet. The current provider integration is exposed through source, health, and markets; built-in studies, strategies, and scripts do not route through BULK yet.

Market Data

Use --provider bulk and omit --exchange. Market Lab resolves the native BULK venue and symbol mapping at the provider boundary.

Check public connectivity:

mlab health --provider bulk

Orderbook

Current snapshot:

mlab source orderbook --provider bulk --symbol BTC/USDT --depth 100

Live reconstructed book:

mlab source orderbook --provider bulk --symbol BTC/USDT --depth 100 --stream --output jsonl

Candles

Historical range:

mlab source candles --provider bulk --symbol BTC/USDT --timeframe 60 --from 1780307559000 --to 1780523645000 --output json

Live candles:

mlab source candles --provider bulk --symbol BTC/USDT --timeframe 60 --stream --output jsonl

Supported BULK timeframe values in seconds are 10, 60, 180, 300, 900, 1800, 3600, 7200, 14400, 21600, 28800, 43200, 86400, 259200, 604800, and 2592000.

Open Interest

BULK open interest is current or live. It does not accept --timeframe, --from, or --to.

mlab source oi --provider bulk --symbol BTC/USDT
mlab source oi --provider bulk --symbol BTC/USDT --stream --output jsonl

Volume

BULK volume output is derived from candle volume and trade count. It is a volume-bar series, not MMT's price-level volume profile.

mlab source volumes --provider bulk --symbol BTC/USDT --timeframe 60 --from 1780307559000 --to 1780523645000 --output json
mlab source volumes --provider bulk --symbol BTC/USDT --timeframe 60 --stream --output jsonl

Volume Delta

BULK volume delta is computed from live taker trades. It is stream-only and does not use --timeframe, --from, --to, or MMT bucket groups.

mlab source vd --provider bulk --symbol BTC/USDT --stream --output jsonl

Statistics

Snapshot statistics can cover all markets or one symbol. Supported periods are 1d, 7d, 30d, 90d, 1y, and all. Streaming requires a symbol.

mlab source stats --provider bulk --period 7d --output json
mlab source stats --provider bulk --symbol BTC/USDT --stream --output jsonl

Funding

mlab source funding --provider bulk --symbol BTC/USDT
mlab source funding --provider bulk --symbol BTC/USDT --stream --output jsonl

Timestamp Boundary

Market Lab accepts application timestamps in milliseconds and converts them only inside the BULK adapter. JSON output uses ts_ms.

Market Catalog

List the embedded BULK catalog:

mlab markets
mlab markets --provider bulk

Inspect one market:

mlab markets --provider bulk --symbol BTC/USDT

The single-market output includes:

• BULK venue symbol and Market Lab internal symbol
• trading status
• base and quote assets
• price and size precision
• tick size and lot size
• minimum notional
• maximum leverage
• supported order types
• supported time-in-force values

--provider bulk is currently the catalog command default. The command does not require an MMT API key, BULK agent wallet, or network connection.

Symbol Mapping

Market Lab stores provider-native and internal symbols explicitly:

BULK venue:       BTC-USD
Market Lab input: BTC/USDT

Lookup is case-insensitive and accepts either slash or dash notation. For the embedded USD markets, these inputs resolve to the same catalog entry:

• BTC/USDT
• BTC/USD
• BTC-USD

The provider boundary owns this mapping. Commands do not reconstruct BULK symbols from display text.

JSON

Add --json for machine-readable catalog data:

mlab markets --provider bulk --json

The full catalog includes:

• schemaVersion
• provider
• sourceUrl
• fetchedAt
• markets

Filter to one market when an agent only needs one rule set:

mlab markets --provider bulk --symbol BTC/USDT --json

Single-market JSON returns the market object directly rather than the full catalog envelope.

Snapshot Behavior

The catalog is sourced from BULK's exchangeInfo endpoint, saved in Market Lab, validated when loaded, and embedded into the CLI binary.

mlab markets does not call BULK at runtime. This keeps symbol and trading-rule lookup deterministic and removes a network dependency from future order validation. It also means the installed binary does not discover rule changes automatically.

Use fetchedAt to identify the snapshot age. A changed listing, tick size, lot size, minimum notional, leverage limit, order type, or time-in-force rule requires the catalog to be refreshed and a new binary to be built.

This catalog is market metadata, not a live price snapshot. It contains no ticker, orderbook, candle, funding, position, or account state.

Why an Agent Wallet

A BULK agent wallet is an authorized signing key that can act for a main account. It gives the upcoming execution adapter a dedicated credential without storing or repeatedly using the main wallet private key.

BULK documents agent wallets as authorized sub-keys for signed order operations. See the official Agent Wallet API and Transaction Signing documentation.

Set Up

Run:

mlab auth set bulk

Market Lab then:

1. Generates an agent keypair locally.
2. Saves it as pending in the operating system keychain before making the network request.
3. Prompts for the BULK main wallet private key without echoing it.
4. Signs an agent-wallet authorization locally.
5. Sends the signed authorization to BULK.
6. Verifies that BULK confirmed the expected account and agent.
7. Marks the stored agent as active only after confirmation.

The main wallet private key is used for signing and is never stored by Market Lab.

Check Status

mlab auth status

Example active state:

mmt: configured in OS keychain
bulk: configured in OS keychain
  account: <account-public-key>
  agent: <agent-public-key>

Status output contains public identifiers only. It never prints the stored agent private key.

Possible BULK states:

• not configured: no local agent credential exists
• pending registration: an agent exists locally but registration was not confirmed
• configured: BULK confirmed the account and agent

Retry a Pending Registration

If the network request fails or BULK does not confirm registration, run the same command again:

mlab auth set bulk

Market Lab reuses the pending agent instead of generating another one. If the pending credential is already tied to an account, the supplied main wallet key must belong to that same account.

Revoke and Remove

mlab auth remove bulk

For an active agent, Market Lab asks for the matching main wallet private key, signs a revocation, waits for BULK confirmation, and only then removes the local credential.

An unregistered pending agent with no account can be removed locally. A pending agent already tied to an account must be retried first so Market Lab does not discard a key that may have been authorized remotely.

Security Boundary

Market Lab stores the following BULK values in the operating system keychain:

• credential format version
• registration state
• account public key when known
• agent public key
• agent private key

The main wallet private key:

• is entered through a hidden prompt
• is used only to sign authorization or revocation
• is not written to marketlab.toml
• is not stored in the operating system keychain
• is not printed in status or command output

Treat the generated agent as a trading credential. Revoke it with mlab auth remove bulk if the machine or keychain is compromised.

Execution Roadmap

The market catalog and agent wallet establish the validation and credential boundaries for the next BULK work:

1. Signed order execution using the stored agent.
2. Account, order, fill, and position state.

These capabilities are roadmap items, not current commands.