BEST Integration

BEST (Behavioral State Protocol) enables AI agents to interact with dotQuant programmatically. Agents discover available capabilities via a standard manifest at /.well-known/best and interact through structured endpoints, each described by a JSON Schema.

dotQuant exposes all four BEST capabilities:

- Commands — every write the platform supports, from following a symbol to approving a portfolio proposal.
- Queries — synchronous reads of current state: feeds, analyses, portfolios, orders, broker cash and positions.
- Events — live server-sent event streams of symbol prices.
- Workflows — published recipes for the multi-step processes, so agents follow the intended sequence instead of guessing.

Discovery flow:
1. Agent fetches /.well-known/best
2. Reads the manifest — services, capabilities, catalogue URIs
3. Starts interacting without any hard-coded integration

Spec: behavioralstate.io

Root manifest (informational): GET https://baas.dotquant.io/.well-known/best

Declares the platform and provides the URI template for tenant manifests. https://dotquant.io/.well-known/best redirects here, and https://dotquant.io/llms.txt carries the same trailhead in plain text.

Tenant manifest (canonical): GET https://baas.dotquant.io/.well-known/best/{tenantId}

Fully self-contained manifest for your account, with resolved endpoint paths and all four capability definitions (commands, queries, events, workflows). This is the manifest AI agents should use. Through the dotquant.io REST proxy the same manifest is served at /api/best/tenants/{tenantId}/.well-known/best.

Discovery chain:

GET /.well-known/best
  → tenants.manifest URI template
    → GET /.well-known/best/{tenantId}
      → command/query/event/workflow catalogue URIs

Endpoint: GET /api/best/tenants/{tenantId}/commands

Returns every command type your tenant can send — following symbols, compiling strategies, running algorithms, routing signals, managing portfolios, placing orders — each with a dataschema URI pointing to its full JSON Schema:

{
  "commands": [
    {
      "schema": "subscribe-price-feed",
      "version": "1.0",
      "dataschema": "https://dotquant.io/api/best/tenants/{tenantId}/commands/subscribe-price-feed/1.0"
    }
  ]
}

Always fetch the schema before sending a command — payloads are validated strictly (additionalProperties: false).

High-impact commands: entries that place or authorize real orders — submit-order, enable-signal-route, approve-portfolio-proposal, retry-portfolio-execution, dispatch-signal — carry an impact annotation (categories, a warning, and a confirmation requirement). A well-behaved agent surfaces that warning and gets the user's explicit go-ahead before sending them.

Endpoints:

GET /api/best/tenants/{tenantId}/queries
GET /api/best/tenants/{tenantId}/queries/{schema}/{version}
GET /api/best/tenants/{tenantId}/queries/{schema}?param=value

The catalogue lists ~30 queries; executing one is a plain GET with query-string parameters and a synchronous JSON answer. The highlights:

- Market: symbol-search, get-symbol-situation, get-price-variations, get-market-state, get-exchange-session
- Analysis: get-analysis (the AI panel), get-analysis-metrics (Key Metrics), get-fundamentals, get-news-sentiment, get-agent-catalogue
- Strategies: list-theses, run-backtest (a synchronous query — the result comes back in the response), list-algorithms, list-algorithm-signals, list-signal-routes
- Portfolios: list-portfolios, list-portfolio-proposals, portfolio-performance, portfolio-performance-history
- Broker & orders: list-brokers, get-broker-cash, get-broker-position, get-broker-order, list-orders
- Account: get-tenant-profile, list-watchlist-panels, list-price-feeds, list-webhooks

Endpoint: GET /api/best/tenants/{tenantId}/events/stream?correlationId={feedId}

Opening the stream is the subscription. The first event is a SymbolSituationV1 — the latest stored price with its freshness status and baseline — followed by event-driven PriceTickV1 frames as new bars arrive. Frames carry an explicit Currency, so pence-quoted instruments are already normalised.

Use it when an agent needs to watch a symbol rather than poll get-symbol-situation.

Clients that can't set headers (a browser EventSource, a URL-only integration): exchange your API Key for a short-lived read-only token at the manifest's tokenUrl (see Agent Authentication below), then open the canonical stream with &access_token= appended:

https://baas.dotquant.io/api/best/tenants/{tenantId}/events/stream?correlationId={feedId}&access_token=<token>

The token expires after ~10 minutes and can never send commands — your real API Key never belongs in a URL.

Endpoints:

GET /api/best/tenants/{tenantId}/workflows
GET /api/best/tenants/{tenantId}/workflows/{id}

The index lists every published recipe; each recipe returns ordered steps with guidance — which command or query to use, with what, and what to check before the next step. They are strictly descriptive: the agent still sends each command itself.

Nine workflows are published today: add-symbol-to-watchlist, research-a-symbol, organize-watchlist-panels, create-a-strategy, backtest-a-strategy, run-a-strategy-live, design-a-portfolio, manage-a-portfolio, and place-manual-order (ids are prefixed io.dotquant.workflows.). The Agent Playbook walks through a use case for each.

Command descriptions in the catalogue cross-reference their workflow — an agent that fetches a command like configure-portfolio is pointed at the recipe before assembling the flow by hand.