> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Market Sentiment

Classify a short text's sentiment toward a specific asset — a crypto coin OR a US stock ticker — with live market context (price, trend, crypto Fear & Greed, equity/cashtag identity) gathered automatically so the model resolves market-native rhetoric — 'inverse BTC', contrarian/fade language, cashtag proxies — against actual market direction. Subjects resolve via CoinGecko (crypto) with a Finnhub equity fallback for tickers like AAPL/NVDA. Runs on Caddie's task-graph runtime; the action is a signed proxy. Single LLM call, fixed structured output. Ideal for: tweet/headline-triggered trading workflows, sentiment-based alerts, contrarian signal detection. Drop-in replacement for an AI Prompt node doing sentiment classification — the failure mode it fixes is the model never seeing market state.

![AI Market Sentiment logo](https://ai-icon.b3.fun/logo/openrouter)
Catalog action Utility

Classify a short text's sentiment toward a specific asset — a crypto coin OR a US stock ticker — with live market context (price, trend, crypto Fear & Greed, equity/cashtag identity) gathered automatically so the model resolves market-native rhetoric — 'inverse BTC', contrarian/fade language, cashtag proxies — against actual market direction. Subjects resolve via CoinGecko (crypto) with a Finnhub equity fallback for tickers like AAPL/NVDA. Runs on Caddie's task-graph runtime; the action is a signed proxy. Single LLM call, fixed structured output. Ideal for: tweet/headline-triggered trading workflows, sentiment-based alerts, contrarian signal detection. Drop-in replacement for an AI Prompt node doing sentiment classification — the failure mode it fixes is the model never seeing market state.


## At a Glance

| Field | Value |
| --- | --- |
| Action ID | `ai-market-sentiment` |
| Category | Utility |
| Connector | Not required |
| Requires gas | No |
| Funds movement | None declared |
| Tags | `ai`, `llm`, `sentiment`, `openrouter`, `utility`, `market`, `crypto`, `transform`, `text` |

## Payload Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | `string` | Yes | The content to classify \(tweet, headline, news snippet, chat message\). Pass in trigger output \(e.g., {{root.result.text}} for an x-new-tweet trigger\). |
| `subject` | `string` | Yes | The asset\(s\) the sentiment is toward — a crypto coin \(name, symbol, CoinGecko id, or contract address, e.g. 'BTC', 'bitcoin', '0xabc...'\) OR a US stock ticker \(e.g. 'AAPL', 'MARA', 'NVDA'\). Pass a COMMA-SEPARATED list \(e.g. 'BTC,ETH,SOL' or 'AAPL, NVDA', up to 5\) to classify each independently — results come back in 'subjects\[\]'. Each is resolved to a CoinGecko id for crypto; if not a coin, it falls back to a Finnhub equity quote. On a full miss, classification uses bare-text reasoning. |
| `author` | `string` | No | Optional author handle/byline \(e.g., '@VitalikButerin'\). Surface hint to the model only — v1 does not maintain a per-handle reputation map. |
| `includeMarketContext` | `boolean` | No | Master switch for the deterministic market-data gather phase. When false, the action runs as a bare-text sentiment classifier with no market fetches. Default: true. |
| `additionalContext` | `string` | No | Extra context from prior workflow steps to pass to the model \(same semantics as AI Prompt's 'context'\). Stringify JSON if needed. |
| `customGuidance` | `string` | No | Optional domain guidance appended to the system prompt \(e.g., 'This account is known for sarcasm', 'Treat $MARA as a Bitcoin-correlated mining proxy'\). Use sparingly — the prompt already covers crypto rhetoric \(inverse, contrarian, cashtag proxies\). TRUST NOTE: this is operator-authored guidance and is injected OUTSIDE the prompt-injection guard rail \(unlike 'text'/'author'/'additionalContext'\), so set it from workflow config — never wire untrusted user/tweet content into it. |
| `model` | `string` | No | The OpenRouter model to use \(default: 'anthropic/claude-haiku-4.5'\). Any model id from the OpenRouter catalog is accepted. When unset, Caddie runs its configured classifier model. |
| `temperature` | `number` | No | Creativity/randomness for the classification call. Default 0.2 — sentiment should be deterministic, not creative. |
| `maxTokens` | `number` | No | Maximum tokens in the response \(default: 1024, max: 16384\). |

## Result Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sentiment` | `string` | Yes | Classification toward the subject asset. |
| `confidence` | `number` | Yes | Model-reported confidence in the classification \(0.0-1.0\). |
| `reasoning` | `string` | Yes | Short explanation of how the model resolved the text — including market direction usage when relevant. |
| `marketContext` | `object` | Yes | Audit trail of the deterministic gather phase. Echoes exactly what the model was shown so Run History is self-explanatory. |
| `subjects` | `array` | No | Per-subject verdicts, one per resolved subject in input order. Length 1 for a single subject; one per ticker when 'subject' is comma-separated \(e.g. 'BTC,ETH,SOL'\). The top-level sentiment/confidence/reasoning/marketContext mirror subjects\[0\]. Index subjects\[i\] to branch per ticker. |
| `model` | `string` | No | The OpenRouter model that produced the classification. |
| `usage` | `object` | No | OpenRouter token usage for the classification call. |

## Examples

**Workflow node**

```json
{
  "type": "ai-market-sentiment",
  "payload": {
    "text": "Workflow completed",
    "subject": "example-subject"
  },
  "children": []
}
```
  **Test with API**

```bash
curl -X POST "https://api.b3os.org/v1/actions/ai-market-sentiment/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "text": "Workflow completed",
    "subject": "example-subject"
  }
}'
```

**Use expressions for dynamic values**

Payload fields can use workflow expressions such as `{{$trigger.body.amount}}`, `{{$nodes.fetch.result.price}}`, and `{{$props.asset}}` when the value should come from a trigger, prior node, or reusable workflow prop.