Skip to main content
POST
/
trade_research
Trade Research
curl --request POST \
  --url https://api.example.com/trade_research \
  --header 'Content-Type: application/json' \
  --data '
{
  "idea": "<string>",
  "protocol": "<string>",
  "vertical": "dex",
  "tier": "basic"
}
'
{
  "confidence": 0.5,
  "key_drivers": [
    "<string>"
  ],
  "dissent_count": 0,
  "blocker_questions": [
    "<string>"
  ],
  "turns": [
    {}
  ],
  "evidence_citations": [
    {}
  ],
  "framework_context": [
    {}
  ],
  "backtest": {},
  "tx_signature": "<string>",
  "solscan_url": "<string>",
  "settlement_mode": "stub"
}

Body

application/json

Phase 8b — request shape for POST /trade_research.

Free in v1 (no x402 gate). The 7-agent panel reads the trading-oracle corpus filtered by (vertical, protocol) and returns the verdict shape. protocol is required and lower-cased downstream.

​
idea
string
required
Required string length: 3 - 2000
​
protocol
string
required
Required string length: 1 - 64
​
vertical
string
default:dex
Required string length: 1 - 64
​
tier
enum<string>
default:basic
Available options:
basic,
pro

Response

Successful Response

Wire response for POST /trade_research.

Mirrors :class:gecko_core.orchestration.trade_panel.TradePanelVerdict field-for-field. The turns list carries plain dicts so we don't couple this surface to the core's pydantic model when consumers deserialize off the wire.

Issue #14: backtest is the pro-tier-only field that justifies the 3x price delta over basic. Always None on the basic envelope (the handler does not enable the backtest path); always a dict on pro (either real PnL stats, or unbacktestable=True + reason when the price source has no history). Surfacing the unbacktestable shape is intentional — the buyer paid for evidence either way.

​
verdict
enum<string>
required
Available options:
act,
pass,
defer
​
confidence
number
required
Required range: 0 <= x <= 1
​
key_drivers
string[]
​
dissent_count
integer
default:0
Required range: x >= 0
​
blocker_questions
string[]
​
turns
Turns · object[]
​
evidence_citations
Evidence Citations · object[]

S35-#99 — 'the data'. Protocol/market-data chunks a panel turn referenced via its inline [N] marker (provider_kind in protocol_native / market_data / paysh_live / bazaar_live). Each entry: {id, source, url, chunk_id, provider_kind, freshness_tier, snippet}. Breaking change: replaces the old single citations[].

​
framework_context
Framework Context · object[]

S35-#99 — 'the lens'. Investor-canon chunks (provider_kind canon_*) the panel reasoned over. Same item shape as evidence_citations. Not relevance-trimmed: canon is cross-cutting.

​
backtest
Backtest · object

Pro-tier only. Realized-history replay of the Strategist intent (pnl_pct, drawdown_pct, hit_rate, source) or {'unbacktestable': True, 'reason': '...'} when the price corpus can't satisfy. Always None on the basic envelope.

​
tx_signature
string | null

Solana on-chain x402 settlement signature; null in stub mode.

​
solscan_url
string | null

Solscan deep link for tx_signature; null in stub mode.

​
settlement_mode
enum<string>
default:stub

Whether real money moved on chain. Canonical literal lives in gecko_core.types.SettlementMode (Pattern A).

Available options:
stub,
live