An open-source, near-real-time cross-chain quantitative trading agent that bridges Solana DEXs and the Injective Helix exchange. It pairs an offline market-research pipeline with a live nBBO (national best bid/offer) engine, deterministic pre-trade risk checks, and a natural-language quant assistant — all exposed as an on-chain ERC-8004 agent that also serves its own MCP endpoint.
Status: research & demo prototype. It can prepare and persist trade plans and run the full pipeline end-to-end with zero paid API keys (mock fallbacks). Solana signing is not wired; Injective trades are simulated unless you provide a testnet mnemonic. Not production trading software.
- Offline research pipeline — crawl CoinMarketCap + TradingView + Dune, clean & normalize, run an LLM analysis, emit BUY/SELL strategy signals.
- Realtime nBBO engine — aggregate quotes across Solana DEXes (Jupiter/Raydium/Orca) and Injective Helix into a single cross-chain best bid/offer.
- Cross-chain arbitrage scanner — detect BTC/ETH spreads between Solana and Injective, net of bridge cost.
- Deterministic risk gate — slippage / notional / liquidity / oracle-deviation caps applied to every prepared trade (LLM never has execution authority).
- Natural-language quant assistant — ask "find me an arb for BTC between Solana and Injective" and get a plan via LangChain tools.
- ERC-8004 agent identity — our agent registers on the Injective Identity Registry and
exposes its own MCP server (
POST /mcp) with 4 callable tools. - Provider-neutral usage ledger — optional cost controls for Dune / CMC / LLM / JEV with Postgres as source of truth + Redis hot-path cache.
- Typed decision quality gate (JEV) — optional shadow/enforce gate for research signals.
Empty state — before the first pipeline run:
After running the pipeline — crawl counts, LLM analysis, trade signals, and the cross-chain arbitrage panel populate:
Agent identity card, nBBO snapshot, and the cross-chain arbitrage scanner:
The cross-chain arbitrage scanner flags BTC/ETH net edge after bridge cost:
Prepare a trade — the nBBO pipeline runs (Pyth oracle → DEX aggregation → route selection → risk check) and a plan summary card appears:
The trade event feed streams lifecycle events over WebSocket and recent trades persist to Postgres:
| Tool | Why | Min version |
|---|---|---|
| Node.js | backend + frontend | 20.x |
| npm | dependencies | 10.x |
| Docker Desktop | local Postgres / Redis | latest |
supabase CLI |
local Postgres (npx supabase start) |
latest (via npx) |
| Git | clone | any |
No Phantom wallet, no real Solana DEX traffic, no real funds needed for the demo. Solana trades are mock-signed; Injective trades are simulated unless you set
INJECTIVE_MNEMONIC.
The demo runs end-to-end with just a local Postgres — every external API has a safe default or mock fallback.
# From the repo root — starts Postgres + Supabase Studio at http://localhost:54323
npx supabase startStandalone Postgres alternative: if
supabase startis too slow, run a plain Postgres container instead:docker run -d --name sol-pg -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:16-alpine docker exec sol-pg psql -U postgres -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp";'Then set
DATABASE_URL="postgresql://postgres:postgres@127.0.0.1:5432/postgres".
cd backend
cp .env.example .env # only DATABASE_URL is strictly required
npm install
npm run db:generate # generate Prisma client
npm run db:push # sync schema to Postgres (creates all tables)
npm run start:dev # http://localhost:3000Verify it's up:
curl http://localhost:3000/health
# → {"status":"ok",...}cd ../frontend
npm install
npm run dev # http://localhost:5173Open http://localhost:5173. The top-right Realtime WS + Offline WS indicators should turn green. You're ready to explore.
The frontend has two pages, linked in the top nav.
This is the default route. It runs the offline research pipeline: crawl → clean → normalize → LLM analysis → strategy signals.
- Click Run pipeline now (triggers
POST /agent/run-pipeline). - The Pipeline Live Feed card streams
pipeline.started/pipeline.completedWebSocket events in real time. - When it completes, the page auto-refreshes and you'll see:
- Last Run Summary — crawl counts (CMC, TradingView, Dune) + duration.
- Latest LLM Analysis — the generated insight (mock text if no LLM key).
- Trade Signals — BUY/SELL with reasons from the momentum strategy.
- Recent Market Data — the ingested rows.
- Cross-Chain Arbitrage — Solana ↔ Injective spread panel.
Without any API keys, the LLM falls back to deterministic demo output and Dune uses
mock data (DUNE_USE_MOCK=true), so the pipeline still produces a full result.
Verify via curl
curl -X POST http://localhost:3000/agent/run-pipeline | jq
curl 'http://localhost:3000/agent/analysis?limit=3' | jq
curl 'http://localhost:3000/agent/signals?limit=10' | jqClick ⚡ Live Trading in the top nav.
Top — Injective Agent Identity (ERC-8004):
- Shows our agent's on-chain identity card (Agent ID, builder code, network, MCP
endpoint). Without
INJECTIVE_AGENT_IDit shows a deterministic simulated card; set it to fetch the real on-chain record. SetINJECTIVE_AGENT_REGISTRY_ENABLED=trueto do a live scan of registered agents (otherwise clearly-labelled samples are shown).
Market data cards:
- Oracle SOL/USDC — live Pyth price (mock-friendly via
PYTH_USE_MOCK=true). - Best Bid / Best Ask / Spread — aggregated nBBO from the configured DEXes.
Prepare a trade:
- Pick a pair from the dropdown (Solana pairs: SOL/USDC, BTC/USDC, ETH/USDC; Injective pairs: INJ/USDC, BTC/USDT, ETH/USDT).
- Choose Buy or Sell, enter an amount (USDC) and max slippage (bps).
- Click Prepare nBBO Trade → the backend runs the full pipeline:
Pyth oracle → DEX aggregation → nBBO selection → risk check → trade persisted as
RealtimeTrade(status=READY). - A green plan summary card appears with the selected DEX, quote price vs oracle price, liquidity, price impact, and route latency.
- Click any lifecycle button to simulate execution:
- Mark Submitted → status
SUBMITTED+ fake tx signature. - Mark Confirmed → status
CONFIRMED+ records execution price. - Mark Failed → status
FAILEDwith a rejection reason.
- Mark Submitted → status
Cross-Chain Arbitrage Scanner:
- Lists live BTC/ETH spreads across Solana and Injective, net of bridge cost, with the recommended direction (e.g. "Buy on Solana, sell on Injective · deBridge/Peggy").
Natural-Language Quant Assistant:
- Type e.g. "Find BTC and ETH arbitrage between Solana and Injective" → click Ask Agent → returns a plan via LangChain tools.
Trade Event Feed & Recent Trades:
- The event feed streams lifecycle events (
trade.intent.received→trade.plan.ready→trade.confirmed) over WebSocket. - Recent trades persist to Postgres so they survive refreshes.
Verify via curl
curl 'http://localhost:3000/realtime/market/nbbo?pair=SOL/USDC' | jq
curl -X POST http://localhost:3000/realtime/trade/prepare \
-H 'content-type: application/json' \
-d '{"pair":"SOL/USDC","side":"buy","amountIn":"160000000","maxSlippageBps":100}' | jq
curl 'http://localhost:3000/realtime/cross-chain/arb' | jq
curl 'http://localhost:3000/agent/identity' | jq
# MCP tools/list (JSON-RPC over Streamable HTTP)
curl -X POST http://localhost:3000/mcp \
-H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'All default off — turn on only what you need.
| Toggle | What it does |
|---|---|
ENABLE_SCHEDULER=true (+ REDIS_URL) |
BullMQ runs the offline pipeline on a configurable interval (default 1h). |
ENABLE_REAL_DEX=true (+ SOLANA_RPC_URL) |
Swap the mock DEX for live Jupiter/Raydium/Orca quotes. |
ENABLE_INJECTIVE=true |
Register the Injective Helix adapter + Injective executor (on by default in .env.example). |
INJECTIVE_MNEMONIC=… |
Let the spawned Injective MCP server sign real testnet orders (empty → simulated). |
LLM_PROVIDER=deepseek + DEEPSEEK_API_KEY |
Replace mock LLM analysis with real DeepSeek output. |
LLM_PROVIDER=openai + OPENAI_API_KEY |
Use OpenAI (or an OpenAI-compatible gateway like OpenRouter). |
LLM_PROVIDER=azure + AZURE_OPENAI_* |
Use Azure OpenAI (Nova Program credits). |
DECISION_PROVIDER=jev + TYPESAFE_API_KEY |
Enable the JEV typed-decision quality gate (start in shadow mode). |
USAGE_LEDGER_ENABLED=true (+ REDIS_URL) |
Turn on provider-neutral cost controls for Dune/CMC/LLM/JEV. |
INJECTIVE_AGENT_REGISTRY_ENABLED=true |
Live on-chain scan of the Injective Agent Registry. |
From the backend/ directory:
npm run db:generate # generate Prisma client
npm run db:push # sync Prisma schema to the live DB (preferred for demo)
npm run db:migrate # apply SQL migrations from supabase/migrations/
npm run db:reset # reset DB and re-run all migrations
npm run start:dev # NestJS dev server with hot-reload
npm run test # Jest unit tests
npm run test:vitest # Vitest unit tests (realtime core / nBBO / Pyth)
npm run test:all # Jest + Vitest
npm run test:workflow # deterministic gather→analyze→decide workflow sim
npm run build # nest buildcd backend && npm run test:all && npx nest build
cd ../frontend && npm run buildThis project is being extended for the Injective Nova Program (Injective × Microsoft × Web3Labs). The story is bidirectional:
- We consume the official Injective MCP server for execution (Helix market data + MCP signing).
- We expose our own MCP server at
POST /mcp(Streamable HTTP) with four tools:query_cross_chain_nbbo,propose_arb_plan,execute_injective_trade,get_agent_identity— so other Injective agents can discover and call us.
| Env var | Default | Description |
|---|---|---|
ENABLE_INJECTIVE |
true |
Register the Helix adapter + Injective executor. |
INJECTIVE_NETWORK |
testnet |
testnet or mainnet. |
INJECTIVE_EXCHANGE_API |
https://api.injective.exchange |
Helix REST base URL. |
INJECTIVE_MCP_BIN |
npx -y @injectivelabs/mcp-server |
Command to spawn the official MCP server (stdio). |
INJECTIVE_MNEMONIC |
(empty) | Empty → MockInjectiveTradeExecutor (simulated tx hashes). Set → real testnet orders. |
INJECTIVE_AGENT_ID |
(empty) | Empty → deterministic simulated identity card. Set → real on-chain record. |
INJECTIVE_AGENT_REGISTRY_ENABLED |
false |
true → live bounded scan of registered agents. |
MCP_PUBLIC_URL |
http://localhost:3000/mcp |
Public URL declared in our Agent Card services. |
# Backend with Injective enabled (testnet, simulated execution)
cd backend
ENABLE_INJECTIVE=true INJECTIVE_NETWORK=testnet npm run start:dev
# Real signing via the official MCP server (advanced)
ENABLE_INJECTIVE=true INJECTIVE_NETWORK=testnet \
INJECTIVE_MNEMONIC="your testnet mnemonic" \
npm run start:devWith ENABLE_INJECTIVE=true and no mnemonic, the Helix adapter fetches real Injective
orderbooks and trades are simulated — safe for demos.
The agent also supports the Monad chain — an EVM-compatible L1 (chain ID 143,
mainnet live since 2025-11-24, ~10k TPS). The integration is fully additive and gated
behind ENABLE_MONAD (default false), so the app behaves identically to before when the
flag is off. See docs/monad-integration-research.md for the full design and
docs/monad-integration-roadmap.md for the ticket-by-ticket implementation plan.
| Env var | Default | Description |
|---|---|---|
ENABLE_MONAD |
false |
Register the Monad DEX adapter + viem executor. Off → no behavior change. |
MONAD_RPC_URL |
(empty) | Monad JSON-RPC endpoint. Empty → mock mode (no network calls). |
MONAD_CHAIN_ID |
143 |
Monad mainnet chain id. Use 10143 for testnet. |
MONAD_DEX_MODE |
mock |
mock → deterministic quotes tracking Pyth mid + premium; aggregator → 0x/1inch API. |
MONAD_AGGREGATOR |
0x |
0x or 1inch when MONAD_DEX_MODE=aggregator. |
MONAD_AGGREGATOR_API_KEY |
(empty) | Required only for 0x Pro / 1inch API in non-demo environments. |
MONAD_PRIVATE_KEY |
(empty) | EVM private key for MonadViemExecutor. Empty → MockMonadTradeExecutor (simulated hashes). Keep in .env only — never commit. |
MONAD_MOCK_OFFSET_BPS |
30 |
Premium (bps) the mock adapter adds over the Pyth mid, used in the nBBO path. |
cd backend
ENABLE_MONAD=true MONAD_DEX_MODE=mock MONAD_PRIVATE_KEY="" npm run start:devWith ENABLE_MONAD=true and no private key / RPC, the Monad adapter returns
deterministic quotes (Pyth mid + MONAD_MOCK_OFFSET_BPS premium) and the executor
returns simulated tx hashes — safe for demos. The Live Trading page dropdown then
exposes three extra pairs tagged Monad DEX (MON/USDC, WBTC/USDC, WETH/USDC), the
nBBO panel can surface a Monad best quote, and the Cross-Chain Arbitrage Scanner
widens to Solana ↔ Injective ↔ Monad (N-chain pairwise scan). Execute a Monad plan
via the Execute on Monad (viem) button or POST /realtime/trade/monad-execute.
⚠️ TheMONAD_TOKENSERC-20 contract addresses inbackend/src/config/tokens.tsare partially verified:WMON(0x32d31642963c202C68724beA3A8dEceb735fca23) is confirmed, whileUSDC/USDT/WBTC/WETHremain TODO placeholders (0xMONAD...) pending verification against the live Monad ecosystem contracts. Mock mode bypasses them; do not enableMONAD_DEX_MODE=aggregatoror set a realMONAD_PRIVATE_KEYuntil those addresses are verified — a real signature against a wrong ERC-20 could lose funds.
Before flipping ENABLE_MONAD=true with real signing in any non-demo environment, the
operator must clear these gates (tracked in docs/monad-integration-roadmap.md):
- Pyth MON feed — confirm a published Pyth price feed id for the Monad-native assets you intend to quote (currently the registry reuses shared BTC/ETH feed ids).
- Paid Monad RPC — provision a paid/mainnet
MONAD_RPC_URL; the public RPC may rate-limit at demo volumes. - 0x / 1inch API key — obtain
MONAD_AGGREGATOR_API_KEYif you switchMONAD_DEX_MODE=aggregator; the free tier is demo-only. - Verified ERC-20 addresses —
WMONis verified (0x32d31642963c202C68724beA3A8dEceb735fca23); replace the remaining0xMONAD...placeholders inMONAD_TOKENS(USDC/USDT/WBTC/WETH) with real on-chain contract addresses. - Funded signer — fund the EVM address derived from
MONAD_PRIVATE_KEYwith enough MON for gas; testnet faucet is free, mainnet is not.
None of these are required for the zero-key demo path above.
| Component | Technologies |
|---|---|
| Backend | NestJS 10 + TypeScript |
| Database | Supabase / PostgreSQL |
| ORM | Prisma |
| LLM | LangChain (DeepSeek / OpenAI / Azure OpenAI adapters) |
| Decision gate | TypeSafe JEV (typed decision models) |
| Job queues | BullMQ + Redis |
| Real-time | Socket.IO |
| Frontend | Vite + React 18 + TypeScript + Tailwind + Zustand |
| Cross-chain | Injective Helix adapter + Injective MCP server + viem (ERC-8004) |
| Symptom | Fix |
|---|---|
prisma generate / db:push fails |
Ensure npx supabase start finished; DATABASE_URL matches the printed local URL. |
Using standalone Postgres, db:push errors on uuid_generate_v4 |
Run CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; in the DB first. |
| Frontend WS indicators stay red | Backend not up, or VITE_BACKEND_URL wrong; check browser console — /socket.io must return 200. |
| No Injective quotes | ENABLE_INJECTIVE=true? The Helix adapter hits https://api.injective.exchange; outbound HTTPS must be allowed. |
| LLM returns "mock" text | The selected DeepSeek/OpenAI/Azure adapter has no key; configure its provider-specific credential. |
| Pyth oracle shows "Waiting for Pyth…" | Set PYTH_USE_MOCK=true for a reliable demo (hermes.pyth.network can be TLS-blocked for Node fetch on some networks). |
TS2589 type errors in cross-chain-agent.service.ts |
Known LangChain+zod inference issue, suppressed with @ts-ignore; runtime unaffected. |
- Manual (run + Azure deploy)
- Architecture
- Code walkthrough
- AI agent rules
- Offline agent design
- Realtime agent design
- Usage ledger design
- Usage ledger roadmap
- Operator pending decisions
- Progress tracker
sol_trade_agent/
├── docs/ # documentation + images
├── backend/ # NestJS backend
│ ├── src/
│ │ ├── agents/ # LLM adapters + factory
│ │ ├── crawlers/ # CMC / Dune / TradingView
│ │ ├── decision/ # JEV quality gate
│ │ ├── usage-ledger/ # provider-neutral cost controls
│ │ ├── realtime/ # nBBO + cross-chain agent + MCP server
│ │ ├── scheduler/ # BullMQ offline pipeline controller
│ │ ├── config/ # ConfigService + token registry
│ │ └── prisma/ # Prisma module
│ ├── prisma/schema.prisma # database schema
│ └── .env.example # all config knobs documented inline
├── frontend/ # Vite + React + Tailwind SPA
│ └── src/pages/ # InsightsPage + LiveTradingPage
├── supabase/migrations/ # SQL migrations (parallel to Prisma)
└── docker-compose.yml # optional local Redis
Built for the Solana Frontier Hackathon · Demo build. Not production trading software.





