Agentic AI

dotQuant is fully compliant with the BEST (Behavioral State Protocol), enabling AI assistants — such as Claude, Cursor, and other MCP-capable tools — to discover your account's capabilities and act on your behalf, authenticated under your account.

An agent connected to your account can do what you can do in the UI: research symbols, manage watchlists, compile / backtest / run strategies, route signals, design and manage portfolios, and place orders — with the money-moving steps annotated high-impact so the agent asks you first. The Agent Playbook walks through each use case.

Two transports are available:

REST transport: AI agents call dotquant.io directly using your API Key. The web server acts as a secure proxy — it validates authentication, then forwards requests server-side.

MCP transport: Use @behavioralstate/best-mcp (stdio) — the reference MCP server for any BEST-compliant endpoint — to connect any MCP-compatible AI tool to your dotQuant account. Configure it with your API Key and Tenant ID.

All agentic interactions are scoped to your tenant — an agent can only access your own feeds, strategies, portfolios, and broker connections.

All tenant-scoped BEST endpoints require authentication via your dotQuant API Key.

Header format:

Authorization: Bearer <your-api-key>

Where to find your credentials — go to your Account page in the dashboard:
- Tenant ID: shown at the top of the Account card. Use the copy button to copy it.
- API Key: shown on the AI Configuration page (the sparkle icon in the topbar). Click Generate New API Key if you haven't created one yet.

The key is tied to your Tenant ID — agents do not need to manage separate session tokens.

Token exchange for header-constrained clients (BEST 0.9.8): a client that cannot set HTTP headers can trade the long-lived key for a disposable one. POST form fields grant_type=client_credentials, client_id=, client_secret= to the manifest's tokenUrl:

POST https://baas.dotquant.io/api/best/auth/token

The response carries a short-lived (~10 min) read-only access_token accepted as a ?access_token= query parameter on the canonical BaaS endpoints (RFC 6750 §2.3) — enough for queries, catalogues and event streams, never for commands. That trade is the point: the credential that rides a URL is disposable, and your real API Key stays out of URLs, logs and browser history.

Security note: the web proxy receives your Bearer token, extracts the key, and forwards it as X-Api-Key to the internal BaaS service. Your API Key is never stored in the browser or logs.

An agent that knows only the manifest can still end up with a configured connection. The root manifest at https://baas.dotquant.io/.well-known/best lists a second service, io.dotquant.onboarding, at /api/best/tenants/public — an anonymous surface with one workflow, create-an-account (the device-authorization pattern, RFC 8628). You appear once: to approve the agent.

What the agent does:
1. get-onboarding-info — what dotQuant is, how BEST works, and what you will be asked to approve.
2. request-registration — a fresh UUID as CorrelationId (its device code) and a short label naming the client, e.g. Claude Desktop on my laptop.
3. get-registration — answers a short user code (XXXX-XXXX) and the activation link, https://dotquant.io/activate?code=…, which the agent shows you.
4. It polls get-registration (never faster than the interval it names) until you have decided.
5. Approved → it exchanges the device code at the manifest's tokenUrl (grant_type=urn:ietf:params:oauth:grant-type:device_code) and receives the tenant id, the API key (shown once), a ready-made MCP configuration block for @behavioralstate/best-mcp, and plain-HTTP instructions for clients that cannot run MCP servers.

What you do: open the link, sign in — or create an account if you are new — and you land on the activation page under your account. It shows the agent's label and the code; tick that you understand what the agent will be able to do, then Approve or Deny. Approving lets the agent do on your account what you can do in the app. Your account holds one API key, so approving replaces any key you already have; the page tells you live when the agent has collected it. Codes expire 15 minutes after the agent asked.

Rules: an agent cannot create an account on its own — your approval is the point. Only the activation page can approve or deny; there is no BEST command for it, so an agent holding a key cannot approve another agent. You can cut an agent off at any time by generating a new key on the AI Configuration page, which also shows who the current key was issued to.

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

Authentication: Required (Bearer API Key)

Content-Type: application/json

Commands are sent in CloudEvents wire format:

{
  "specversion": "1.0",
  "id": "unique-event-id",
  "source": "https://your-agent.example.com",
  "type": "<CommandType>",
  "datacontenttype": "application/json",
  "dataschema": "<catalogue dataschema URI>",
  "time": "2026-07-12T11:20:00Z",
  "data": { }
}

Response (201 Created) returns the correlation id of the accepted command.

Copy dataschema verbatim from the catalogue entry (the relative schema/version form also works). source is your agent's own identity, any URI-reference — the server derives queue routing from the command itself and overwrites source, so no special value is required. data must conform to the command's JSON Schema — fetch it first via the catalogue's dataschema URI; payloads are validated strictly (unknown fields in data are rejected, while unknown envelope attributes are ignored per CloudEvents 1.0).

The @behavioralstate/best-mcp package — the reference MCP server for BEST-compliant endpoints — exposes your dotQuant account as an MCP (Model Context Protocol) server, letting Claude Desktop, Cursor, and other MCP-compatible AI tools interact with your account natively. No install step is needed; npx fetches it on demand.

Configuration (add to your MCP client's config):

{
  "mcpServers": {
    "dotquant": {
      "command": "npx",
      "args": ["-y", "@behavioralstate/best-mcp"],
      "env": {
        "BEST_DOTQUANT_BASE_URL": "https://baas.dotquant.io/api/best",
        "BEST_DOTQUANT_TENANT_ID": "<your-tenant-id>",
        "BEST_DOTQUANT_API_KEY": "<your-api-key>"
      }
    }
  }
}

Once configured, your AI assistant discovers the command, query, and workflow catalogues and can explore your feeds, read analyses, run strategies, and manage portfolios conversationally.