Recipe Building Blocks

Composable parts catalog for AIXBT recipes (v1.1). Recipes run on all surfaces: CLI, MCP, and REST API. Examples below use CLI syntax, but the YAML is the same everywhere. Pick the blocks you need, wire them together, and write analysis instructions for the assembled data.

This document complements the Recipe Specification (formal schema) and the CLI Guide (command workflows). The spec tells you what's valid YAML; this doc tells you what to put in it.

Recipe registry: 21 production recipes live in a remote registry. Use aixbt recipe list to see all available recipes and aixbt recipe info <name> to view a recipe's details. Clone with aixbt recipe clone <name> to inspect or customize the full YAML. These are the best source of working patterns. When in doubt, read an existing recipe that does something similar to what you're building.

Cloning and customizing: aixbt recipe clone <name> copies a registry recipe to ~/.aixbt/recipes/ with a .clone suffix (both filename and name: field). Use --name <newName> to choose your own name, --out <dir> for a different directory.

1. Provider Action Catalog

Every action available in recipe steps, grouped by provider. Use action (required) and source (optional, defaults to "aixbt") to invoke them.

Virtual providers (market, security, defi) are provider-agnostic entry points that route to the best concrete backend. Use these in recipes for portability and smart routing. You can also use concrete providers (coingecko, dexpaprika, goplus, defillama) directly when you need a specific backend.

Dotted syntax: source: market.coingecko forces a shared action to use a specific backend. Without the dot, the virtual provider picks the default.

For live discovery: aixbt provider list -f json returns all actions with params and tier requirements. aixbt provider <source> <action> -f json runs an action outside a recipe for testing.

AIXBT

Market (virtual provider)

On-chain price, pool, and OHLCV data. Routes across CoinGecko/GeckoTerminal and DexPaprika backends. Use source: market in recipe steps.

Smart routing: Shared actions (token-ohlcv, token-pools, pool-ohlcv) default to DexPaprika (fast, keyless). Use dotted syntax (source: market.coingecko) to force a specific backend. CoinGecko-only actions always route to CoinGecko regardless of hint.

Chain name mapping: All actions that take a network param accept CoinGecko platform IDs (e.g., "ethereum", "solana", "base"). The CLI maps them to the backend's network IDs automatically.

Commonly Used

Shared Actions (default: DexPaprika)

These exist on both DexPaprika and CoinGecko. Default to DexPaprika; override with source: market.coingecko.

CoinGecko-Only Actions

Concrete CoinGecko Actions

These are available directly via source: coingecko (not through the market virtual provider). Most require a demo key; ohlc is free tier.

Security (virtual provider)

Token and address security analysis via GoPlus. Use source: security in recipe steps. All actions are free tier.

Aliases: token-scan → security-check, address-scan → address-security. These work in recipes but the GoPlus action names are preferred.

DeFi (virtual provider)

DeFi protocol data via DeFiLlama. Use source: defi in recipe steps.

Chain name mapping: The chain param accepts CoinGecko platform IDs (e.g., "ethereum"). The CLI maps them to DeFiLlama chain names (e.g., "Ethereum").

2. AIXBT Response Shapes

Field semantics for AIXBT's own data objects. External provider responses vary and are best discovered by running the action. These shapes are stable and under our control.

Project

id: string                    # Unique project identifier (MongoDB ObjectId)
name: string                  # Display name ("solana", "Euro Coin")
description: string?          # Brief project description (not always present)
xHandle: string               # Twitter/X handle
spikingScore: number         # Current breakout momentum (0-1+). Higher =
                                mentions, authors, and communities are accelerating.
                                Measures velocity, not raw volume.
activeScore: number       # Count of hours in the last 24h with at least one mention.
                                This is recent activity coverage, not sustained growth.
                                High active coverage + low momentum = active but not accelerating.
                                Low active coverage + high momentum = emerging from a smaller base.
climbingScore: number           # 72h attention accumulation score. Rewards rising 4h buckets,
                                final-day growth, author/cluster breadth, and penalizes bursts.
rank: number?                 # Position in the top 100 (1-100). Null/omitted = unranked.
                                The leaderboard is volatile: ~570 unique projects appear in
                                any given week, and most swing widely or drop off entirely.
                                Treat as directional, not a stable position.
momentumContext: {             # Pre-computed momentum and leaderboard stability context.
                                Only present when explicitly included in transform.select.
  trajectory: string           # Pre-classified momentum direction: rising/stable/declining/spike
  distinctClusters: number     # Number of distinct clusters currently tracking this project
  peakRank48h: number?         # Best rank position in the last 48 hours
  bestRank14d: number?         # Best rank position in the last 14 days
  rankedSince: string?         # ISO date when the project first entered the top 100
  leaderboard: {
    top10: {                   # Top-10 presence context (null if never in top 10)
      stabilityLabel: string   # flash (<2h), fresh (2-6h), persistent (6-24h), durable (>=24h)
      currentHours: number     # Hours continuously in current top-10 position
      wasYesterday: boolean    # Whether the project was in top 10 yesterday
      entryCount24h: number    # Times entered top 10 in last 24h (>1 = churn)
    }?
    top25: { ... }?            # Same shape as top10, for top-25 presence
  }
}
metrics: {
  usd: number                 # Current price in USD
  usdMarketCap: number        # Market capitalization
  usd24hVol: number           # 24-hour trading volume
  usd24hChange: number        # 24-hour price change (percentage as decimal, e.g. -0.09 = -9%)
  lastUpdatedAt: number       # Unix timestamp of last price update
}
tokens: [{                    # On-chain token addresses (for wallet/holder analysis and
                                external provider lookups)
  chain: string               # Blockchain ("ethereum", "solana", "base", etc.). This is
                                the CoinGecko platform ID, accepted by all provider chain params
  address: string             # Contract/mint address. CASE-SENSITIVE for Solana.
  source: string              # Data source ("coingecko", "dexscreener")
}]
coingeckoData: {
  symbol: string              # Trading ticker ("SOL", "EURC")
  slug: string                # CoinGecko URL slug
  apiId: string               # CoinGecko API ID (for chart geckoId param)
  description: string         # CoinGecko project description
  contractAddress: string     # Primary contract address
  categories: string[]        # CoinGecko category tags
}
createdAt: string             # When the project was first tracked (ISO date)
reinforcedAt: string          # When the most recent intel was reinforced (ISO date).
                                Stale reinforcedAt = project gone quiet.
intel: [{...}]                # Embedded recent intel (up to 10). ONLY available when
                                select transform is not applied. See Intel below.

Key interpretation patterns:

• spikingScore vs activeScore divergence shows acceleration vs activity coverage. High spiking momentum + low active coverage = emerging from a smaller base. High active coverage + declining momentum = activity without fresh acceleration.
• momentumContext.leaderboard.stabilityLabel calibrates rank significance. Flash positions (<2h) are the norm — most projects hold top-10 for under 2 hours. Persistent (6-24h) and durable (>=24h) positions indicate genuine sustained attention. Use this instead of manually interpreting rank history.
• metrics.usd24hChange should be read against BTC/ETH context. A project down 5% while BTC is down 8% is outperforming.
• tokens[].chain + tokens[].address are the data pointers for external provider lookups. Feed them to chart, security-check, etc.
• coingeckoData.apiId is the key for the chart action's geckoId param (CEX fallback path), CoinGecko actions that take an id param, and DeFiLlama emissions.

Intel

id: string                    # Unique intel identifier
detectedAt: string            # When the intel was FIRST observed (ISO date)
reinforcedAt: string          # When the intel was LAST confirmed (ISO date).
                                Gap between detectedAt and reinforcedAt shows repeat reinforcement.
description: string           # Human-readable intel summary (substantive claim, not raw source text)
projectName: string           # Display name of the related project
projectId: string             # Project ID (for joining to project data)
category: string              # One of:
                                  TECH_EVENT         # Protocol upgrades, launches, audits
                                  TOKEN_ECONOMICS    # Unlocks, burns, staking changes
                                  PARTNERSHIP        # Integrations, collaborations
                                  FINANCIAL_EVENT    # TGEs, airdrops, funding rounds
                                  MARKET_ACTIVITY    # Exchange listings, liquidity events
                                  ONCHAIN_METRICS    # TVL changes, volume shifts, holder movements
                                  WHALE_ACTIVITY     # Large wallet movements, accumulation
                                  VISIBILITY_EVENT   # Media mentions, influencer attention
                                  OPINION_SPECULATION # Community predictions, sentiment shifts
                                  TEAM_UPDATE        # Team changes, governance decisions
hasOfficialSource: boolean    # Whether at least one source is from the project's own channels.
                                Official source = first-party confirmation.
clusters: [{                  # Which community clusters are represented
  id: string
  name: string
}]
activity: [{                  # Reinforcement timeline (optional, include via select)
  date: string                # When this reinforcement occurred
  source: string              # Platform ("x", "discord", "telegram")
  clusters: [{ id, name }]    # Contributing clusters
  incoming: string            # Raw observation text
  result: string              # Processed intel text after this reinforcement
  isOfficial: boolean         # Whether this specific source is an official channel
}]

Key interpretation patterns:

• detectedAt vs reinforcedAt gap: Intel reinforced over multiple days across multiple clusters = genuine sustained attention. Detected and never reinforced = noise.
• category determines intel type. TECH_EVENT and TOKEN_ECONOMICS are most concrete (verifiable, quantifiable). VISIBILITY_EVENT and OPINION_SPECULATION are least actionable alone.
• hasOfficialSource = true elevates credibility. TOKEN_ECONOMICS intel from the project itself is near-certain; without official source, could be speculation.
• clusters array length: 1 cluster = early/niche. 5+ clusters = broad awareness, likely priced in.
• activity array: Accelerating reinforcement (more frequent, more clusters) = growing conviction. Decelerating = narrative exhaustion.

Momentum

projectId: string
projectName: string
data: [{
  timestamp: string           # Hour bucket (ISO date, hourly granularity)
  spikingScore: number       # Momentum for that hour (0-1+)
  clusters: [{                # OPTIONAL (only with includeClusters=true)
    id: string
    name: string
    count: number             # Mentions from this cluster in this hour
  }]
}]

Key interpretation patterns:

• Curve shape matters more than any single value. Climbing climb = organic growth. Sharp spike = event-driven (check intel). Spike then decay = attention didn't stick. V-shape = revival.
• Without clusters (includeClusters: "false"): momentum values only. Sufficient for direction/timing analysis.
• With clusters: see which account archetypes drive each phase. Single-cluster spike = concentrated attention. Multi-cluster spike = broader coverage.
• Hourly granularity: 168 data points per 7 days. High-resolution but data-heavy.

Cluster

id: string                    # Cluster identifier (referenced by intel.clusters and momentum.clusters)
name: string                  # Short label ("VC", "Researcher", "Trencher")
description: string           # Community characterization (topics, key accounts, behavior)

Key interpretation patterns:

• Community clusters are overlapping account archetypes. Multiple clusters detecting the same intel = broader cluster coverage; check source and reinforcement details for confirmation.
• First-party project announcements are exposed through hasOfficialSource / isOfficial, not a special cluster.
• Cluster diversity on intel or a project is a coverage indicator. Single-cluster = concentrated. Multi-cluster = information has crossed account archetype boundaries.

Source Identity Tagging

When a for: step iterates over projects and fetches from an external provider, the results automatically carry source identity fields copied from the source item:

_source_id: string            # Copied from item.id or item._id
_source_name: string          # Copied from item.name
_source_symbol: string        # Copied from item.symbol (if present)
_source_slug: string          # Copied from item.slug (if present)

These let you correlate external enrichment data back to the parent project. When hints.combine joins data by key: "id", source identity tagging is how for: step results from external providers match up with project data.

3. Shaping Data for Inference Quality

Transforms (sample and select) exist to improve the quality of agent inference, not primarily to reduce costs. An agent given 50K tokens of unfocused data produces worse analysis than one given 15K tokens of the right data. Sample to focus on high-value items; select to strip fields that add noise without analytical value.

The measurements below (production API, 2026-03-15, post-select, pre-sample) help you understand where data mass comes from so you can make informed decisions about what to keep and what to cut.

Per-Block Token Costs

Rules of Thumb

10-project recipe, 14d momentum (no clusters), per-project intel, narrative arc, clusters: ~3,000 + (10 × 400) + (10 × 120) + (10 × 2,100) + 11,500 + 570 ≈ 41K tokens

Where to focus your shaping:

• Intel data dominates. BROAD_INTEL with activity is ~28K alone. If the agent doesn't need the reinforcement timeline, drop activity from select, which accounts for 76% of the intel data mass. Sample to guarantee the most relevant intel surfaces first.
• includeClusters: "false" on momentum when the recipe already fetches clusters separately. The per-cluster breakdown is useful for deep analysis but adds ~40% per project without adding new information if clusters are already in context.
• Embedded intel in projects (~4,500/project when select is omitted) duplicates what a dedicated intel fetch provides with better coverage and field control. Apply select to strip it when you have a dedicated intel step.
• External provider data (chart, security-check, emissions) varies per project. Always use fallback so missing data degrades gracefully rather than failing the recipe.

Embedded Intel Rule

Projects include an embedded intel array (up to 10 recent pieces of intel). The select transform strips these. The rule:

• Apply select (drop embedded intel) when the recipe has a dedicated intel fetch for those projects, either PER_PROJECT_INTEL with for: projects.data or BROAD_INTEL joined via key: "projectId:id". The dedicated fetch gives better coverage with sampling and field control.
• Omit select (keep embedded intel) when the recipe's intel coverage may not include every project in the set. The embedded intel is then the only per-project intel context available.

Broad vs Per-Project Intel

Two approaches to intel data with different coverage characteristics:

Many recipes use both: broad intel for cross-project patterns, per-project intel for focused analysis. This is complementary, not redundant: broad intel surfaces patterns between projects that per-project fetches miss.

4. Writing Instructions and Fallbacks

Recipes have two instruction surfaces: what the engine injects automatically and what the recipe author controls. Understanding the boundary helps you write instructions that complement rather than duplicate what the agent already receives.

What the Engine Injects

The engine adds context at multiple points, and none of this needs to be in your recipe YAML:

System prompt. Every agent invocation receives a system prompt explaining AIXBT's domain: what clusters, intel, and momentum scores mean, how to interpret the data structures, and what tools are available (web search, file reading). You don't need to explain these concepts in your instructions.

Action context hints. The engine scans which actions your recipe uses and injects domain-specific interpretation guidance:

• intel steps → how to read intel categories, reinforcement patterns, and community spread
• momentum steps → how to interpret momentum curves, inflection points, and cluster engagement
• clusters steps → what clusters represent and how cross-cluster detection indicates broader coverage

Field context hints. When your select transform includes specific fields, the engine adds field-level guidance:

• activity in select → explains the reinforcement timeline array, source platforms, and how to read acceleration/deceleration patterns

Sampling notes. When a sample transform runs, the engine notes that the data was sampled (not exhaustive) and what guarantee/random split was applied.

Parallel execution instructions. For parallel agent steps (type: agent with for:), the engine generates detailed instructions explaining:

• Which context steps contain per-item data (for: steps matching the same source array) vs shared data (non-for: steps or for: over different arrays)
• How to spawn parallel agents and what data each receives
• The expected resume format matching the returns schema

What the Recipe Author Controls

instructions on agent steps. This is where you tell the agent what to do with the data. Focus on:

• What analytical question to answer (not what the data fields mean; the engine handles that)
• Which data relationships to examine (e.g., "map momentum inflection points to intel catalysts")
• What output structure you want (the returns schema defines types, but instructions define quality expectations)
• When to use external tools (e.g., "web search for project news and team background")

analysis block. Instructions for the final synthesis after all steps complete. Template expressions ({params.*}) are resolved at execution time. The analysis agent receives all step results. Use this for:

• How to structure the final output
• Cross-cutting analysis directives (e.g., "compare projects by momentum phase alignment")
• Output format expectations

fallback on API steps (including those with for:). The fallback string becomes an instruction to the agent when a step is skipped or items fail. The engine wraps your text in context:

For API steps (entire step skipped due to missing/insufficient provider key):

Step "<id>" was skipped: no <source> API key configured. <your fallback text>

For for: steps (individual items that fail):

<your fallback text> for: <item1>, <item2>, <item3>

Failed for: items preserve identity fields (id, name, symbol, slug) so the agent knows which items need alternative handling.

Write fallbacks as agent instructions, not error messages. Good: "Look up 90-day price data for this project." Bad: "Price data unavailable." The agent can often fulfill the request via web search or other tools if you tell it what to look for.

Instruction Writing Tips

• Don't explain AIXBT domain concepts. The system prompt and action context hints already cover what momentum scores, intel categories, and clusters mean.
• Do explain analytical intent. "Assess whether momentum is driven by genuine adoption intel or visibility noise" gives the agent a framework; "spikingScore is a number from 0-1" wastes instruction tokens.
• Reference _item in parallel agent instructions. For for: agent steps, the current project's data is available as _item. List what the agent has: "You have: _item (project metadata), intel (48h intel), momentum (14-day trajectory)".
• Keep returns schemas minimal. The agent produces the analysis in its returns, and a projectId: "string" + analysis: "string" pair is usually sufficient. Over-structured returns constrain the agent without improving output quality.

Instruction Anti-Patterns

Common mistakes in recipe instructions that reduce output quality:

Entity enumeration vs structural patterns. Instructions that ask the agent to "list all clusters discussing this project" or "name every community cluster" produce noisy, unhelpful output. Cluster names are internal identifiers -- readers do not know what every account archetype means. Instead, instruct the agent to report the structural pattern: how many clusters, whether the count is expanding or contracting, and the coverage rate.

Bad:

List all clusters discussing this project and what each one is saying.

Good:

Report cluster engagement: count of community clusters represented,
whether that count is expanding (new clusters appearing) or contracting
(clusters dropping off), and the coverage rate across account archetypes.

Raw field enumeration vs analytical framing. Instructions that say "report the spikingScore, activeScore, climbingScore, and metrics.usd24hChange" produce data readbacks, not analysis. The agent already has the data; it needs instructions on what to do with it.

Bad:

For each project, report: spikingScore, activeScore, climbingScore, 24h change,
cluster count, intel count, and market cap.

Good:

For each project, assess whether momentum is driven by genuine adoption
intel or visibility noise. Flag divergences where momentum and price
are moving in opposite directions.

5. Reusable Step Blocks

Copy-paste YAML templates. Adapt id, params, and transforms to your recipe's needs.

Project Discovery

SPECIFIED_PROJECTS

Fetch user-named projects by ID, ticker, name, or contract address.

params:
  projectIds: { type: string, description: "Comma-separated project IDs" }
  tickers: { type: string, description: "Comma-separated ticker symbols (e.g. SOL,ETH)" }
  names: { type: string, description: "Comma-separated project names" }
  address: { type: string, description: "Token contract address" }
requiredOneOf: [projectIds, tickers, names, address]

steps:
  - id: projects
    type: api
    action: projects
    params:
      projectIds: "{params.projectIds}"
      tickers: "{params.tickers}"
      names: "{params.names}"
      address: "{params.address}"
    transform:
      select: [id, name, description, xHandle, spikingScore, activeScore, climbingScore, momentumContext, metrics, tokens, coingeckoData, createdAt, reinforcedAt]

Position: First step. Uses requiredOneOf so the user can identify projects by whichever method they have. The API accepts any one of these filters. Template resolution skips params that weren't provided.

Use when: The user specifies which projects to analyze (assessment, comparison, portfolio, deep dive).

SPIKING_PROJECTS

Fetch projects ranked by momentum (attention spreading to new clusters).

- id: spiking
  type: api
  action: projects
  params:
    limit: 10
    sortBy: spikingScore
  transform:
    select: [id, name, description, xHandle, spikingScore, activeScore, climbingScore, momentumContext, metrics, tokens, coingeckoData, createdAt, reinforcedAt]

Position: First step. limit can be hardcoded or use {params.projectLimit}.

Use when: The recipe explicitly needs fast momentum or "what's spiking right now". For broad discovery, prefer CLIMBING_PROJECTS so one-off spikes do not dominate the candidate set. Note: momentumContext includes leaderboard stability labels (flash/fresh/persistent/durable) that indicate how long a project has held its top-list position.

Variants:

• With chain: "{params.chain}", which filters to a specific blockchain
• As a reference set (id: spiking_rankings) with select: [id, name, spikingScore, momentumContext] for lightweight comparison data

ACTIVE_PROJECTS

Fetch projects ranked by recent active-hour coverage.

- id: active_projects
  type: api
  action: projects
  params:
    limit: "{params.projectLimit}"
    sortBy: activeScore

Position: First step. No select transform, which keeps embedded intel since these recipes often don't have a dedicated per-project intel fetch.

Use when: Comparing recent active-hour coverage against spiking or climbing-growth rankings.

DERIVED_PROJECTS

Fetch project details for projects referenced in upstream intel data.

- id: projects
  type: api
  action: projects
  params:
    projectIds: "{intel.data[*].projectId}"
  transform:
    select: [id, name, description, xHandle, spikingScore, activeScore, climbingScore, momentumContext, metrics, tokens, coingeckoData, createdAt, reinforcedAt]

Position: After a broad intel fetch. The {intel.data[*].projectId} expression extracts unique project IDs from the intel results.

Use when: Intel-first recipes where intel determines which projects matter.

CLIMBING_PROJECTS

Fetch projects ranked by climbing growth.

- id: climbing
  type: api
  action: top-projects-climbing
  params:
    limit: 10
    chain: "{params.chain}"

Position: First step for broad discovery/watchlist recipes, or alongside SPIKING_PROJECTS for explicit spike-vs-accumulation contrast. Optional project filters mirror projects. No transform.select needed — the response shape includes climbingScore, rationale, market data, intel, and momentumContext.

Use when: The recipe needs to find what is accumulating attention across recent buckets, not just what is spiking right now. Combines well with SPIKING_PROJECTS to contrast current spikes against slower multi-bucket growth.

Intel

BROAD_INTEL

Market-wide recent intel, not filtered to specific projects.

- id: intel
  type: api
  action: intel
  params:
    reinforcedAfter: "-48h"
    sortBy: reinforcedAt
  transform:
    sample:
      tokenBudget: 50000
      guaranteeCount: 30
    select: [id, detectedAt, reinforcedAt, description, projectName, projectId, category, hasOfficialSource, clusters]

Use when: Market-wide intel landscape before narrowing to specific projects. Essential for discovery, narrative tracking, risk scanning.

Variants:

• With clusterIds: "{params.clusterId}" for a cluster-scoped view
• Lookback window: -48h (standard), -24h (freshness-critical)
• With activity in select, which adds the reinforcement timeline (data-heavy: +76% more tokens)

PER_PROJECT_INTEL

Per-project intel fetch via for: modifier.

- id: intel
  type: api
  for: projects.data
  action: intel
  params:
    projectIds: "{item.id}"
    reinforcedAfter: "-48h"
  transform:
    sample:
      tokenBudget: 50000
      guaranteeCount: 30
    select: [id, detectedAt, reinforcedAt, description, projectName, projectId, category, hasOfficialSource, clusters]

Use when: Every project in the set needs its own intel assessment. Guarantees coverage for each project.

Variants:

• reinforcedAfter: "-48h" (recent) vs detectedAfter: "-7d" (extended)
• Configurable window: reinforcedAfter: "{params.intelWindow}"

NARRATIVE_ARC

Sampled 30-day intel timeline for story evolution.

- id: narrative
  type: api
  for: projects.data
  action: intel
  params:
    projectIds: "{item.id}"
    detectedAfter: "-30d"
  transform:
    sample:
      tokenBudget: 50000
      guaranteePercent: 0.3
    select: [description, detectedAt]

Use when: The recipe needs to distinguish genuine narrative development from recycled hype. Complements PER_PROJECT_INTEL (recent detail) with historical trajectory.

for: target variants: projects.data (direct), picks.projectIds (after agent gate), filter.projectIds (after filter).

Context

MOMENTUM_HISTORY

Per-project momentum trajectory.

- id: momentum
  type: api
  for: projects.data
  action: momentum
  params:
    id: "{item.id}"
    start: "-14d"
    includeClusters: "false"

Use when: The recipe needs momentum direction, not just the current value. Essential for timing assessments.

Windows: -7d (snapshot, ~1,200 tokens/project), -14d (standard, ~2,100), -30d (full arc, ~3,100). All without clusters.

CLUSTERS

All cluster definitions.

- id: clusters
  type: api
  action: clusters

No params, no transform. Reference data; place in hints.include.

MARKET_CONTEXT

BTC and ETH as macro reference.

- id: market_context
  type: api
  action: projects
  params:
    projectIds: "66f4fdc76811ccaef955de3e,66f4fe366811ccaef955dfc7"
  transform:
    select: [id, name, metrics, coingeckoData]

Hardcoded BTC and ETH project IDs. Place in hints.include.

External Enrichment

PRICE_HISTORY

Per-project price candles via the market virtual provider.

- id: price_history
  type: api
  for: projects.data
  action: chart
  source: market
  params:
    network: "{item.tokens[0].chain}"
    address: "{item.tokens[0].address}"
    geckoId: "{item.coingeckoData.apiId}"
    timeframe: day
    limit: 30
  fallback: "Look up 30-day price data for this project."

Use when: The recipe needs price context for momentum or intel analysis. The chart action uses on-chain DEX data (via DexPaprika, free) when address is available, falls back to CoinGecko OHLC when only geckoId is available. Use source: market.coingecko to force the CoinGecko backend for shared actions.

Fastest path: Always pass network + address when available. The on-chain DexPaprika path is keyless, free-tier, and avoids the extra CoinGecko ID lookup, making it the most performant route for chart. The geckoId param is a fallback for projects that lack token addresses.

Variants:

• timeframe: hour, limit: 168 for 7-day hourly candles (fine-grained intraday analysis)
• limit: 90 for extended history (project_deep_dive)
• limit: 14 for a short window (under_the_radar)

Always include fallback. Not all projects have tokens with addresses, and provider keys may not be configured.

TOKEN_SECURITY

Per-project security scan via the security virtual provider.

- id: token_security
  type: api
  for: projects.data
  action: security-check
  source: security
  params:
    chain: "{item.tokens[0].chain}"
    address: "{item.tokens[0].address}"
  fallback: "Look up holder concentration and token security for this project."

Use when: The recipe needs risk assessment, including honeypot checks, holder concentration, and mint authority. The security-check action routes to the correct chain-specific endpoint automatically.

Always include fallback. Many projects lack token addresses.

TOKEN_UNLOCKS

Per-project emission schedule via the defi virtual provider.

- id: token_unlocks
  type: api
  for: projects.data
  action: emissions
  source: defi
  params:
    coingeckoId: "{item.coingeckoData.apiId}"
  fallback: "Look up token emission/unlock schedule for this project."

Use when: The recipe assesses supply-side risk (TOKEN_ECONOMICS intel). Requires DeFiLlama pro key.

Always include fallback. Requires pro key, and not all projects have emission data.

Orchestration

AGENT_GATE

Single agent that filters or selects from upstream data, returning IDs for downstream enrichment.

- id: picks
  type: agent
  context: [intel, projects]
  instructions: |
    Review the upstream data and select 2-3 projects that would
    benefit most from deeper enrichment. Return project IDs.
  returns:
    projectIds: "string[]"

Use when: Discovery pattern. Start broad, narrow down before deeper per-project enrichment. Creates a segment boundary: steps after this reference picks.projectIds, not projects.data.

Variants:

• returns: { picks: "{ intelId: string, reasoning: string }[]" } for structured picks with reasoning
• returns: { projectIds: "string[]" } (most common, simple ID list)

PARALLEL_AGENT_GATE

Per-project agent analysis via for: modifier.

- id: project_analyses
  type: agent
  for: projects.data
  context: [intel, narrative, momentum, price_history, clusters, market_context]
  instructions: |
    Analyze this specific project. You have:
    - _item: project metadata
    - intel, narrative, momentum, price_history: per-project data
    - clusters, market_context: shared reference data

    Produce a structured assessment...
  returns:
    projectId: "string"
    projectName: "string"
    analysis: "string"

Use when: Each project needs independent, in-depth analysis that would be too much to do in a single pass. The CLI fans out to concurrent agent invocations.

Context steps are automatically classified as per-item (for: steps matching the same source) vs shared (non-for: steps). The agent receives _item (the current project) plus its per-item data and all shared data.

6. Composition Patterns

How blocks combine into complete recipes. Each pattern is a proven arrangement from the recipe registry.

Full Project Profile

For user-specified projects requiring comprehensive per-project data.

SPECIFIED_PROJECTS → PER_PROJECT_INTEL + NARRATIVE_ARC + MOMENTUM_HISTORY + CLUSTERS + MARKET_CONTEXT

Optionally add: PRICE_HISTORY, TOKEN_UNLOCKS, TOKEN_SECURITY, PARALLEL_AGENT_GATE.

Hints: combine: [projects, intel, narrative, momentum], key: "id", include: [clusters, market_context]

Examples: project_deep_dive, project_comparison, project_snapshot

Discovery with Selective Drill-Down

Start broad, use an agent to pick targets, then enrich the picks.

CLIMBING_PROJECTS + BROAD_INTEL → AGENT_GATE → NARRATIVE_ARC (on picks) + CLUSTERS + MARKET_CONTEXT

The agent gate creates a segment boundary. Pre-gate steps scan broadly (10-15 projects). Post-gate steps enrich only 2-3 picks. This focuses token budget on high-value candidates.

Examples: intel_scanner, daily_digest

Intel-First Discovery

Intel determines which projects matter, not a spiking, climbing, or active ranking.

BROAD_INTEL → DERIVED_PROJECTS → AGENT_GATE → MOMENTUM_HISTORY + PER_PROJECT_INTEL + NARRATIVE_ARC + CLUSTERS + MARKET_CONTEXT

Unique property: the project set is discovered from intel data ({intel.data[*].projectId}), not fetched directly. The agent then filters this intel-derived set.

Examples: smart_money_filter, drama

Multi-Project Discovery + Parallel Agent

Broad discovery with per-project parallel analysis.

CLIMBING_PROJECTS + PER_PROJECT_INTEL + NARRATIVE_ARC + MOMENTUM_HISTORY + CLUSTERS + MARKET_CONTEXT + [PRICE_HISTORY] + [TOKEN_SECURITY] → PARALLEL_AGENT_GATE

No single-agent gate. All projects get full enrichment and independent agent analysis. Higher token budget but produces structured per-project assessments that the final analysis synthesizes.

Examples: catalyst_scanner, momentum_decay, narrative_revival, sentiment_tracker, under_the_radar

Dual-List Divergence

Compare two different project rankings to find gaps and overlaps.

CLIMBING_PROJECTS + ACTIVE_PROJECTS + BROAD_INTEL + MOMENTUM_HISTORY + CLUSTERS + MARKET_CONTEXT

Two project sets side by side. The analysis looks for divergence: projects climbing but not active (emerging from a smaller base), active but not climbing (active but not accumulating), or appearing in both (broad attention with multi-bucket growth). Add SPIKING_PROJECTS only when the recipe explicitly needs spike-vs-accumulation contrast.

Examples: sentiment_tracker

Lightweight Scan

Minimal context for focused assessments.

CLIMBING_PROJECTS (or ACTIVE_PROJECTS) + PER_PROJECT_INTEL + MOMENTUM_HISTORY + CLUSTERS

No market context, no narrative arc, no external enrichment. Just current state. Lowest token budget (~25-30K).

Examples: surge_analysis, risk_scan, chain_scanner, narrative_tracker, daily_market_insights

Market Overview + Agent-Driven Enrichment

Broad scan with agent selecting targets for deeper context.

CLIMBING_PROJECTS + BROAD_INTEL + PRICE_HISTORY → AGENT_GATE → NARRATIVE_ARC (on picks) + CLUSTERS + MARKET_CONTEXT

Similar to Discovery with Selective Drill-Down but starts with price history on all projects before the agent gate. The agent uses price context to make better selections.

Examples: daily_digest

7. Worked Examples

Two recipes illustrating core patterns. The registry has 22 more. Use aixbt recipe list to browse and aixbt recipe show <name> to dump full YAML.

Project Deep Dive: Parallel Agent + requiredOneOf

Full profile pattern with requiredOneOf params, multi-step per-project enrichment, and parallel agent gate. The agent step fans out per-project with per-item vs shared context classification. Condensed from the registry version (aixbt recipe show project_deep_dive for full instructions).

name: project_deep_dive
version: "1.0"
estimatedTokens: 32000
description: |
  Extended multi-section analysis with 90-day price history and full narrative arc.
  - Use when building a thesis or doing comprehensive research on a project.

params:
  projectIds: { type: string, description: "Comma-separated project IDs" }
  tickers: { type: string, description: "Comma-separated ticker symbols (e.g. SOL,ETH)" }
  names: { type: string, description: "Comma-separated project names" }
  address: { type: string, description: "Token contract address" }
requiredOneOf: [projectIds, tickers, names, address]

steps:
  - id: projects
    type: api
    action: projects
    params:
      projectIds: "{params.projectIds}"
      tickers: "{params.tickers}"
      names: "{params.names}"
      address: "{params.address}"
    transform:
      select: [id, name, description, xHandle, spikingScore, activeScore, climbingScore, momentumContext, metrics, tokens, coingeckoData, createdAt, reinforcedAt]

  - id: narrative
    type: api
    for: projects.data
    action: intel
    params:
      projectIds: "{item.id}"
      detectedAfter: "-30d"
    transform:
      sample: { tokenBudget: 50000, guaranteePercent: 0.3 }
      select: [description, detectedAt]

  - id: intel
    type: api
    for: projects.data
    action: intel
    params:
      projectIds: "{item.id}"
      reinforcedAfter: "-48h"
    transform:
      sample: { tokenBudget: 50000, guaranteeCount: 30 }
      select: [id, detectedAt, reinforcedAt, description, projectName, projectId, category, hasOfficialSource, clusters]

  - id: momentum
    type: api
    for: projects.data
    action: momentum
    params:
      id: "{item.id}"
      start: "-30d"
      includeClusters: "false"

  - id: climbing_rankings             # shared reference, not per-project
    type: api
    action: top-projects-climbing
    params: { limit: 25 }
    transform:
      select: [id, name, climbingScore, spikingScore, momentumContext]

  - id: clusters                    # shared reference
    type: api
    action: clusters

  - id: price_history
    type: api
    for: projects.data
    action: chart
    source: market
    params:
      network: "{item.tokens[0].chain}"
      address: "{item.tokens[0].address}"
      geckoId: "{item.coingeckoData.apiId}"
      timeframe: day
      limit: 90
    fallback: "Look up 90-day price data for this project."

  - id: project_analyses
    type: agent
    for: projects.data          # parallel, one agent per project
    context: [narrative, intel, momentum, price_history, climbing_rankings, clusters]
    instructions: |
      Produce project research on this project. You have:
      - _item: project metadata (name, metrics, coingeckoData, tokens)
      - narrative, intel, momentum, price_history: per-project data
      - climbing_rankings, clusters: shared reference data
      Write a structured report: Narrative Arc, Fundamental Assessment,
      Momentum Assessment, Market Context, Key Risks, Assessment.
    returns:
      projectId: "string"
      projectName: "string"
      assessment: "string"
      analysis: "string"

hints:
  combine: [projects, intel, momentum, narrative, price_history]
  key: "id"
  include: [climbing_rankings, clusters, project_analyses]

analysis:
  instructions: |
    Present per-project research reports from parallel agents. Add
    cross-project synthesis if multiple projects: sector overlap,
    momentum phase alignment, cluster overlap, narrative convergence.
  output: |
    Detailed research report per project, plus cross-project
    synthesis if applicable.

aixbt recipe run project_deep_dive --tickers SOL
aixbt recipe run project_deep_dive --names "solana,ethereum"

Intel Scanner: Discovery with Agent Gate

Discovery pattern using an agent to select drill-down targets. Demonstrates the segment boundary: post-gate for: uses picks.projectIds. Includes 7-day daily price candles via the market virtual provider.

name: intel_scanner
version: "1.1"
estimatedTokens: 26000
description: |
  Broad intel scan with ticker extraction and tiered conviction scoring.
  - Use when scanning for actionable intel across the full market.
  - Clone to filter by intel categories or add custom scoring criteria.

params:
  projectLimit:
    type: number
    required: false
    default: 10
    description: "Number of top projects to cross-reference"

steps:
  - id: recent_intel
    type: api
    action: intel
    params:
      reinforcedAfter: "-48h"
    transform:
      sample:
        tokenBudget: 50000
        guaranteeCount: 30
      select: [id, detectedAt, reinforcedAt, description, projectName, projectId, category, hasOfficialSource, clusters]

  - id: active_projects
    type: api
    action: top-projects-climbing
    params:
      limit: "{params.projectLimit}"
    transform:
      select: [id, name, description, xHandle, spikingScore, activeScore, climbingScore, momentumContext, metrics, tokens, coingeckoData, createdAt, reinforcedAt]

  - id: price_history
    type: api
    for: active_projects.data
    action: chart
    source: market
    params:
      network: "{item.tokens[0].chain}"
      address: "{item.tokens[0].address}"
      geckoId: "{item.coingeckoData.apiId}"
      timeframe: day
      limit: 7
    fallback: "Look up 7-day price data for this project."

  # --- Segment boundary ---
  - id: picks
    type: agent
    context: [recent_intel, active_projects, price_history]
    instructions: |
      Cross-reference the broad intel scan with the top momentum
      projects. Projects appearing in both with substantive intel
      categories and multi-cluster detection are the strongest
      candidates for deeper investigation.

      Return the project IDs of 2-3 projects that would benefit
      most from 30-day narrative context.
    returns:
      projectIds: "string[]"

  - id: narrative
    type: api
    for: picks.projectIds
    action: intel
    params:
      projectIds: "{item}"
      detectedAfter: "-30d"
    transform:
      sample:
        tokenBudget: 50000
        guaranteePercent: 0.3
      select: [description, detectedAt]

  - id: clusters
    type: api
    action: clusters

  - id: market_context
    type: api
    action: projects
    params:
      projectIds: "66f4fdc76811ccaef955de3e,66f4fe366811ccaef955dfc7"
    transform:
      select: [id, name, metrics, coingeckoData]

hints:
  combine: [recent_intel, active_projects, narrative, price_history]
  key: "projectId:id"
  include: [clusters, market_context]

analysis:
  instructions: |
    Broad intel scan to extract every actionable ticker and classify
    them by conviction strength. Cross-reference intel with momentum
    projects. Score each by intel category weight, cluster diversity,
    reinforcement recency, and momentum trajectory.
  output: |
    Tiered list with: ticker/project name, conviction tier, primary
    intel, cluster count, time since last reinforcement, and one-line
    catalyst summary. High conviction first.

aixbt recipe run intel_scanner