Charlie API

This endpoint exposes Charlie over the public darwintIQ API.

Use it when you want a structured market interpretation in your own application, script, or automation flow instead of only inside the darwintIQ workspace.

Endpoint

POST https://api.darwintiq.com/v1/charlie

Authentication and usage model

Charlie uses the same Bearer token model as the rest of the public API:

-H "Authorization: Bearer [YOUR_TOKEN]"

Charlie also keeps the same plan-based access rules as the browser workspace:

• Single Symbol: only the subscribed symbol, core workflows only, 5 analyses per day for that symbol
• Pro: all supported Charlie symbols, all workflows, 20 analyses per day per symbol, 3 model comparisons per day
• Pro+: all supported Charlie symbols, all workflows, 50 analyses per day per symbol, unlimited model comparisons

Browser usage and API usage count against the same Charlie quota because both are recorded against the same darwintIQ user.

Request body

Field	Required	Type	Description
symbol	No	string	Market symbol. Defaults to EURUSD.
workflowId	No	string	Charlie workflow. If omitted, darwintIQ infers it from the latest user message.
timeframe	No	string	Optional timeframe override such as M15, H1, or D1.
signalMode	No	string	Optional signal mode override when you want Charlie to focus the cluster context.
messages	Yes	array	Conversation thread. At least one user message is required.
messages[].role	Yes	string	user or assistant.
messages[].content	Yes	string	Message content used for the analysis thread.

Supported workflows

• market_briefing
• model_comparison
• opportunity_check
• regime_interpretation
• cluster_explanation
• risk_stability_view

Example request

curl -X POST \
  -H "Authorization: Bearer [YOUR_TOKEN]" \
  -H "Content-Type: application/json" \
  "https://api.darwintiq.com/v1/charlie" \
  -d '{
    "symbol": "EURUSD",
    "workflowId": "market_briefing",
    "timeframe": "M15",
    "messages": [
      {
        "role": "user",
        "content": "What matters most on EURUSD right now?"
      }
    ]
  }'

Python example

import requests

url = "https://api.darwintiq.com/v1/charlie"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
    "symbol": "EURUSD",
    "workflowId": "market_briefing",
    "timeframe": "M15",
    "messages": [
        {
            "role": "user",
            "content": "What matters most on EURUSD right now?"
        }
    ],
}

response = requests.post(url, headers=headers, json=payload, timeout=20)
response.raise_for_status()
data = response.json()

print(data["answer"])
print(data.get("summary", {}).get("bottomLine"))

n8n snippet

This HTTP Request node calls Charlie directly and can be placed into a workflow that forwards the result into Slack, email, Telegram, Notion, or another downstream step.

Store your token as an n8n environment variable such as DARWINTIQ_API_TOKEN, then use a node like this:

{
  "parameters": {
    "method": "POST",
    "url": "https://api.darwintiq.com/v1/charlie",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Authorization",
          "value": "=Bearer {{$env.DARWINTIQ_API_TOKEN}}"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ]
    },
    "sendBody": true,
    "specifyBody": "json",
    "jsonBody": "={\n  \"symbol\": \"EURUSD\",\n  \"workflowId\": \"market_briefing\",\n  \"timeframe\": \"M15\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What matters most on EURUSD right now?\"\n    }\n  ]\n}"
  },
  "name": "Charlie API",
  "type": "n8n-nodes-base.httpRequest",
  "typeVersion": 4.2
}

Response example

{
  "answer": "EURUSD still looks constructively aligned, but the more important point is that the move reads as orderly rather than explosive. Trend alignment and model quality are supportive, yet the setup is not broad enough to treat as one-sided.\n\n- Bias: constructive bullish\n- Confidence: moderate\n- Main risk: leadership can weaken if stability deteriorates while price keeps extending\n\nNot financial advice.",
  "workflowId": "market_briefing",
  "workflowLabel": "Market Briefing",
  "language": "en",
  "symbol": "EURUSD",
  "generatedWith": "openai",
  "selectedTimeframe": "M15",
  "selectedSignalMode": "Breakout",
  "evidence": [
    "Market state: Trend, Strong, Stable, Positive expectancy, Normal volatility",
    "Top model: Breakout on M15 with fitness 22.10, stability 74, EV 0.58"
  ],
  "summary": {
    "bottomLine": "Constructive but not one-sided.",
    "bias": "bullish",
    "confidence": "moderate",
    "regime": "trend",
    "signalFreshness": "fresh",
    "mainRisk": "stability can deteriorate underneath the move"
  },
  "snapshot": {
    "generatedAt": "2026-04-21T10:30:00.000Z",
    "symbol": "EURUSD",
    "workflowId": "market_briefing",
    "workflowLabel": "Market Briefing",
    "timeframe": "M15",
    "signalMode": "Breakout",
    "regime": "Trend",
    "dominantCluster": "Breakout",
    "stability": "Stable",
    "expectancy": "Positive",
    "volatility": "Normal",
    "topModel": "Breakout",
    "latestModel": "Breakout",
    "lastEntryMinutes": 14,
    "generatedWith": "openai"
  }
}

Response fields

Field	Type	Description
answer	string	Charlie's full analyst-style response.
workflowId	string	Effective workflow used for the response.
workflowLabel	string	Human-readable workflow label.
language	string	de or en, inferred from the latest user prompt.
symbol	string	Effective symbol used for the analysis.
generatedWith	string	openai or heuristic, depending on which generation path succeeded.
selectedTimeframe	string	Effective timeframe used for the context load.
selectedSignalMode	string | null	Effective signal mode when available.
evidence	array	Compact evidence lines extracted from the live darwintIQ context.
summary	object | null	Short structured summary block.
snapshot	object | null	Compact machine-readable snapshot of the context used by Charlie.

Errors

Status	Meaning
400	Missing or malformed request body, for example no usable messages.
401	Missing bearer token.
403	Invalid token, missing symbol access, or workflow not included in the current plan.
429	Charlie daily usage limit reached for the symbol or workflow.
500	Internal failure while generating the Charlie response.

Notes

• Charlie is interpretive output, not a trade instruction service.
• model_comparison is blocked on plans that do not include it, even if basic Charlie access is available.
• If you want raw underlying data as well, combine Charlie with /v1/models, /v1/trendmatrix, /v1/supres, or /v1/priceData.

Related docs

• Authentication
• Rate limits and error handling
• Charlie explained
• Using darwintIQ data in Python, n8n, TradingView, or Excel