Skip to main content
Get API Key

Market Events

events conditions trigger on market events: things that happened — a listing, a hack, a regulatory decision, a macro release, a protocol upgrade, company news, a large flow, bullish or bearish news on an asset. They are the events GET /v3/events serves, each written up from many posts into a title, a classification, and the assets and entities it names. A condition fires when a new one matches it. Use events for news about a subject; use tweet for posts from a specific account.

SourceMethodFires when
eventsmatchan event passes every filter you set and, with text, states your claim

What a match gives you, and what it does not: the trigger payload carries the event's id, title, classification, and the entities it names. It carries no link and no summary: fetch them by the event's id from /v3/events, see From the Alert Back to the Event.

events conditions obey the standard limits: they combine with other sources inside AND/OR groups, up to depth 3 and 10 leaf conditions. See Triggers.

Not yet in the app's builder catalog

You can create events conditions through the Auto API and with Builder Chat. The app's visual plan builder does not list the source yet.

Condition Shape​

Write the shorthand. Every argument is optional, but a condition needs at least one filter or text:

{
  "source": "events",
  "args": { "entity": "ETH", "implication": "bearish" }
}

The shorthand expands to method: "match", operator: "==", value: true. The full form is accepted with exactly those values and no others.

Filters​

All filters you set must pass (they are combined with AND). Each takes one value: for "BTC or ETH", or "listing or hack", write several events conditions under OR. The values are those of GET /v3/events, and they match the same way: see From a /v3/events Query.

ArgumentValuesMatches
entityan id from /v3/entities, a ticker or a name, e.g. "ETH", "Hyperliquid", "Michael Saylor"events that name it as a main or a related subject — see Entity Routing
entityTypetoken, equity, project, person, organisationnarrows how entity resolves; requires entity
eventClassmarket, call, assetmarket: a development reported across posts, including news about a specific asset. call: accounts taking positions — calls and targets, not the move itself. Avoid asset (posts about one asset, nothing wider): it is rare, and most news about a named asset is classed market, so filter on entity instead
eventTypesecurity, listing, regulatory, macro, protocol, company, marketFlow, price, social, otherwhat kind of event it is (marketFlow is camelCase)
implicationbullish, bearish, mixed, unclearthe likely direction for the assets the event names
alertActionalert, monitoralert: judged impactful. monitor: worth watching
assetClasscrypto, equitythe class of the assets the event names. Events that name no asset — macro, policy — pass this filter
noveltynew, updatethe event's own call on whether it is a new development. It does not reliably filter repeats of a story — see Runtime Semantics
text + minConfidencea claim, and an integer 0–100a specific claim the event must state — see Filters vs Text. Both or neither

Entity Routing​

entity takes an id, a ticker or a name. Validate and Create resolve it to one entity and store that as entityPublishedId in the plan.

  • An id is exact. Pass entities[].id from GET /v3/entities and the condition names that entity, whatever shares its name or ticker. It is the same id /v3/events takes in entityIds.

A ticker or a name is resolved for you, ticker first, then name:

  • A ticker resolves to that token or stock: "ETH" is Ethereum, "HYPE" is Hyperliquid.

  • A name that is also a ticker resolves to the ticker. "Elon Musk" resolves to a token named MUSK, "Fed" to a stock with the ticker FED, and "BlackRock" to a token named BLACKROCK. For anything that is not a token or a stock, set entityType:

    // bad: resolves to a token named MUSK
    { "entity": "Elon Musk" }

    // good
    { "entity": "Elon Musk", "entityType": "person" }

  • When a name matches several entities equally, Validate rejects it and lists the candidates; when a name also matches weaker alternatives, Validate accepts it and returns a warning naming them. Read the warning: it tells you which entity you got.

  • Central banks, regulators, governments, and macro themes are not entities. Filter on eventType and say the subject in text:

    // bad: resolves to a stock with the ticker FED, not the Federal Reserve
    { "entity": "Fed" }

    // good
    { "eventType": "macro", "text": "the Federal Reserve changes interest rates", "minConfidence": 80 }

Filters vs Text​

Prefer filters. They match exactly, cost nothing to check, and never miss an event that a classifier already tagged. Add text only for a specific claim the filters cannot express.

text is checked against the event's title and summary, and passes when the check's confidence reaches minConfidence. The event's classification never supplies the claim: a stance that only implication carries does not satisfy text.

IntentBadGood
Bearish news on ETH{ "text": "bearish news about ETH", "minConfidence": 80 }{ "entity": "ETH", "implication": "bearish" }
Anything about Solana{ "text": "news about Solana", "minConfidence": 80 }{ "entity": "SOL" }
Exchange hacks{ "eventType": "security" } (also matches protocol exploits and phishing){ "eventType": "security", "text": "a crypto exchange is hacked or exploited", "minConfidence": 80 }

minConfidence is an integer from 0 to 100. Start at 80: lower lets more loosely related events through, higher drops events that state the claim indirectly.

A filter-only condition consumes no credits. A condition with text consumes credits each time an event that passes its filters is checked against the claim.

From a /v3/events Query​

An events condition is a GET /v3/events filter that runs on every new event instead of once. It takes the endpoint's filter values and matches them the same way, so a query that returns what you want to hear about turns into a condition:

GET /v3/eventsevents conditionDifference
entityIds=<id>"entity": "<id>"One entity per condition. A ticker or a name also works, see Entity Routing
eventClass, eventType, implication, assetClass, noveltythe same argument, the same valuesNone. assetClass lets through events that name no asset in both
alertAction=alert"alertAction": "alert"One value. Leave it out for both
Several entityIds, or a list of alertActionseveral conditions under OR
q=<topic>"text": "<claim>" with minConfidenceq ranks events by topic. text is a claim each event must state, checked event by event for credits. See Filters vs Text
from, to, order, sort, eventIds, hasStoryline, notable, arcIdnoneA condition watches events written up from its creation onwards

Preview Before You Create​

Run the query over the last day. What it returns is what a condition with the same filters would have fired on:

1. GET /v3/entities?q=eth&entityType=token&limit=1
      -> entities[0].id: Ethereum

2. GET /v3/events?entityIds=<id>&implication=bearish&from=<now - 1d>
      -> the bearish ETH events of the last day. Too many? Add eventType or
         alertAction=alert. None? Drop a filter
{ "source": "events", "args": { "entity": "<id>", "implication": "bearish" } }

A condition with text fires on fewer: only the events that also state the claim. The /v3 endpoints need a Pay-as-you-go, Grow or Enterprise key. Without one, name the entity by ticker or name, and read the Validate response to see which entity it resolved to.

Runtime Semantics​

  • Event-driven. Conditions are evaluated as events arrive, not on a polling interval.
  • Not a first-post trigger. Events are analysed from many posts, so they arrive minutes to hours after the first post about something. To be first, watch the account that breaks the news with tweet.
  • Fresh events only. An event is matched only while it is less than an hour old. A new plan sees events from its creation onwards; nothing is replayed.
  • Each event fires a plan at most once. Without repeat, the first matching event triggers the plan and moves it to a terminal state. With repeat, the plan fires once per matching event.
  • A developing story can fire again. Follow-up reporting on a story arrives as further events, and each can match: about 1 in 9 events continues a story already reported that day, roughly half of them with new facts. novelty: "new" does not reliably remove these: most still read new. To act once per story, compare the event's storylineId (see From the Alert Back to the Event), or use repeat.cooldown to space alerts out.

Trigger Payload​

Each matched events condition reports the condition you wrote and the event that matched it:

{
  "condition": {
    "source": "events",
    "args": {
      "entity": "ETH",
      "entityPublishedId": "c1a2b3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "eventType": "security",
      "text": "a crypto exchange is hacked or exploited",
      "minConfidence": 80
    }
  },
  "match": {
    "eventId": "c26d6d18-2b1f-4b7e-9a7d-5f0f3c3e8a11",
    "title": "Exchange hot wallet drained of $12M in ETH",
    "eventClass": "market",
    "eventType": "security",
    "implication": "bearish",
    "alertAction": "alert",
    "novelty": "new",
    "timeSensitivity": "hours",
    "citedSourceCount": 6,
    "analyzedAt": "2026-10-08T16:02:31.204Z",
    "entities": [
      { "symbol": "ETH", "name": "Ethereum", "entityType": "token" }
    ],
    "confidence": 84
  }
}
  • condition.args — the arguments you wrote, plus entityPublishedId, the entity entity resolved to.
  • match.eventId — the event's id in /v3/events. Each event fires a plan at most once. It is not the webhook delivery's X-Auto-Event-Id, which is the id to deduplicate deliveries on (see Webhook Event Sample).
  • match.title — the event's headline: its alertTitle in /v3/events. There is no summary and no link.
  • match.eventClass, eventType, implication, alertAction, novelty — the event's classification, with the values listed under Filters.
  • match.timeSensitivity — how quickly the event is expected to matter.
  • match.citedSourceCount — how many posts the event cited when it was written up. /v3/events lists them, with links, in citedSources.
  • match.analyzedAt — when the event was written up, as an ISO 8601 timestamp. /v3/events gives the same moment in Unix seconds.
  • match.entities — up to 10 entities the event names, each with name, entityType, and symbol (omitted for people and organisations).
  • match.confidence — the text check's confidence. Absent on filter-only conditions.

From the Alert Back to the Event​

match.eventId is the event's id in /v3/events. With a key that can call /v3, fetch the rest of it there:

GET /v3/events?eventIds=<match.eventId>
    -> summary, citedSources with their links, impacts (price reactions),
       storylineId, and the entities with their ids

To act once per story, keep the storylineId of each event you act on and skip an event whose storylineId you already hold: later reporting on a story carries the same one. storylineId is null on a call event and on an event not threaded into a story; treat those as stories of their own.

Examples​

Urgent Security Events On Crypto Assets​

Fires on each urgent security event, up to 20 times a week, at most once every 15 minutes.

{
  "title": "Crypto security alerts",
  "description": "Notify on urgent hacks and exploits involving crypto assets.",
  "conditions": {
    "AND": [
      {
        "source": "events",
        "args": { "eventType": "security", "alertAction": "alert", "assetClass": "crypto" }
      }
    ]
  },
  "actions": [
    {
      "stepId": "step_1",
      "type": "notify",
      "params": { "message": "[{{title}}] Security event at {{trigger_time}}" }
    }
  ],
  "expiresIn": "168h",
  "repeat": { "cooldown": "15m", "maxTriggers": 20 }
}

For HTTP calls, wrap conditions, actions, expiresIn, and repeat under a top-level query key. See HTTP Request Wrapper.

Bearish News On One Asset​

{
  "source": "events",
  "args": { "entity": "ETH", "implication": "bearish" }
}

Exchange Listings​

{
  "source": "events",
  "args": { "eventType": "listing", "assetClass": "crypto" }
}

A Specific Claim​

{
  "source": "events",
  "args": {
    "eventType": "regulatory",
    "text": "the SEC approves a spot crypto ETF",
    "minConfidence": 80
  }
}

Several Assets​

{
  "OR": [
    { "source": "events", "args": { "entity": "BTC", "eventType": "marketFlow" } },
    { "source": "events", "args": { "entity": "ETH", "eventType": "marketFlow" } }
  ]
}

News And Price Together​

Fires when bullish regulatory news on ETH lands while ETH is up more than 2% in the last hour:

{
  "AND": [
    { "source": "events", "args": { "entity": "ETH", "eventType": "regulatory", "implication": "bullish" } },
    {
      "source": "price",
      "method": "change",
      "args": { "symbol": "ETH", "period": "1h", "exchange": "hyperliquid" },
      "operator": ">",
      "value": 2
    }
  ]
}

Validation Notes​

Error signalWhat it meansNext action
EQL_INVALID_ARG_VALUE with "provide at least one of entity, eventClass, …"The condition has no filter and no text.Add a filter, or text with minConfidence.
EQL_INVALID_ARG_VALUE with "Unknown entity"No asset, project, person, or organisation matches entity (or none of the entityType you set).Check the spelling, try the ticker or the full name, or drop entity and describe the subject with eventType and text.
EQL_INVALID_ARG_VALUE with "Ambiguous entity", candidates in details.candidatesThe name matches several entities equally.Set entityType, or pass the publishedId of the candidate you mean as entity.
EQL_INVALID_ARG_VALUE with "is an asset events never name"The entity resolved to an asset that events do not cover.Pick another entity, or filter on eventType and text.
EQL_MISSING_ARG for minConfidencetext without minConfidence.Add minConfidence (start at 80).
EQL_INVALID_ARG_VALUE on minConfidence, "it applies to 'text'"minConfidence without text.Add text, or remove minConfidence.
EQL_INVALID_ARG_VALUE on entityType, "it narrows 'entity'"entityType without entity.Add entity, or remove entityType.
EQL_INVALID_ARG_VALUE with "expected one of …"A filter value outside its list.Use one of the values in Filters; note marketFlow is camelCase.
EQL_INVALID_JSON with "conditions must be a root AND or OR group …"Usually an argument given as an array, e.g. "entity": ["BTC", "ETH"].One value per argument; write several conditions under OR.
EQL_INVALID_OPERATORThe full form with an operator other than ==, or a value other than true.Use the shorthand.
Warning "… can also mean …"entity resolved, but other entities share the name.Confirm the resolved entity is the one you meant; otherwise set entityType or pass an id.
Plan is active but never firesNo event has matched yet.Loosen filters, check the resolved entity in the Validate warning, and remember events arrive minutes to hours after the first post.