Mobula Enterprise — Charts, TradingView & Swap Routing

Role

FORGE uses a Mobula Enterprise API key for:

1. Chart / OHLCV data — historical bars + real-time candle stream
2. TradingView Charting Library datafeed on Agent / token pages
3. Buy / sell swap quoting and routing — GET /api/2/swap/quoting → user wallet signs MobulaRouter calldata

PONS remains the launch + fee + on-chain event source of truth (indexer). Mobula is the market UX + execution routing layer for charts and swaps. Do not invent a second aggregator.

Official Mobula docs (re-read at integration time):

• https://docs.mobula.io/cookbooks/setup-trading-view-chart
• https://docs.mobula.io/guides/setup-trading-view-chart-with-real-time-crypto-price
• https://docs.mobula.io/rest-api-reference/endpoint/swap-quoting
• https://docs.mobula.io/guides/complete-swap-guide
• https://docs.mobula.io/guides/pool-targeting

Mobula lists Robinhood Chain as evm:4663 for swap routing.

Secrets

MOBULA_API_KEY=                    # Enterprise key — API/worker only, NEVER browser
MOBULA_API_BASE_URL=https://api.mobula.io
MOBULA_WS_URL=                     # from Mobula enterprise docs / dashboard
MOBULA_CHAIN_ID=evm:4663
MOBULA_TRADINGVIEW_ENABLED=true
MOBULA_SWAP_ENABLED=true
MOBULA_DEFAULT_SLIPPAGE_BPS=100    # 1% default UI slippage; user-adjustable

• Browser never receives MOBULA_API_KEY.
• Web TradingView datafeed and swap UI call FORGE API (/api/v1/market/*, /api/v1/swap/*); Fastify proxies to Mobula with the enterprise key.
• Rate-limit and cache Mobula responses in Redis where safe (quotes short TTL; OHLCV longer for historical).

TradingView charts

UX

• Agent page and /token/[address] embed TradingView Charting Library (self-hosted under apps/web static assets per Mobula cookbook).
• Theme: FORGE charcoal / forge-orange accents; respect prefers-reduced-motion for non-essential chart chrome only.
• Resolutions: at least 1, 5, 15, 60, 240, 1D mapped to Mobula period.

Datafeed (server-proxied)

Implement Mobula-style datafeed in apps/web that calls FORGE, not Mobula directly:

Modes (from Mobula cookbook):

• Asset / token mode (mode=asset): chart the token; Mobula routes to highest-liquidity pool. Use for Agent pages when curve vs pool is abstracted.
• Pool / pair mode (mode=pool): pin address to the PONS curve or graduated Uniswap v4 pool when the indexer knows the exact venue.

Prefer pool mode when launches.curve_address or graduated pool is known so the chart matches the tradeable venue. Fall back to asset mode if pool metadata is missing.

Continuity across graduation

Indexer still tracks CURVE → GRADUATING → POOL. Chart should remain one series:

• Pre-grad: pool mode on bonding curve address when Mobula indexes it; else asset mode.
• Post-grad: switch address to the locked v4 pool; avoid resetting the visible history if Mobula provides continuous OHLCV — if not, stitch at graduation timestamp and label the phase boundary in the UI.

Indexed PONS trades remain available for the activity tape; they do not replace Mobula as the TradingView datafeed.

Buy / sell (swap routing)

Flow

1. User opens Buy or Sell on Agent / token page (wallet connected).
2. UI requests quote from FORGE: POST /api/v1/swap/quote.
3. API calls Mobula GET /api/2/swap/quoting with enterprise key.
4. Response returns amounts + EVM tx (data.evm.transaction) via MobulaRouter.
5. Client prompts approve (ERC-20) if needed, then eth_sendTransaction / wagmi send.
6. On success, wait for receipt; indexer + Mobula refresh chart/balances; do not mark fills from quote alone.

Quote request (FORGE → Mobula)

chainId=evm:4663
tokenIn=...
tokenOut=...
amount=... | amountRaw=...
walletAddress=0x...
slippage=...                    # from UI / MOBULA_DEFAULT_SLIPPAGE_BPS
poolAddress=...                 # optional: PONS curve or graduated pool (pool targeting)
onlyProtocols=...               # optional

• Native ETH sentinel per Mobula docs (0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE on EVM).
• Pair asset for PONS launches is the quote token (ETH or approved ERC-20).
• When trading the launch token on its known pool/curve, pass poolAddress so routing prefers that venue (see Mobula pool-targeting guide).
• Opening snipe tax on fresh PONS curves: if Mobula quotes ignore snipe tax, surface a FORGE warning and/or fall back to PONS on-curve quote for the first N seconds — never show a cheaper quote than settlement. Document the active policy in UI copy.

Security

• Slippage bounds enforced server-side (max BPS config).
• Quote TTL short; refuse stale quotes.
• Simulate / decode Mobula tx to against expected MobulaRouter allowlist for evm:4663 before returning to client.
• Never custody; user wallet always signs.
• Log quote ids / route metadata without logging the API key.

FORGE API surface

GET  /api/v1/market/ohlcv          # TradingView getBars proxy
GET  /api/v1/market/symbols        # resolve token/pool for chart
GET  /api/v1/market/price          # optional spot helper
POST /api/v1/swap/quote            # Mobula swap quoting proxy
POST /api/v1/swap/prepare-approval # optional spender + amount helper from quote

WebSocket: either extend forge-ws with market.ohlcv events fed from a Mobula WS subscriber in worker/indexer, or have the TradingView datafeed use a short-lived authenticated SSE from API. Prefer one server-side Mobula WS fan-out to many browsers (enterprise key stays server-side).

Package layout

packages/market/          # Mobula client, types, quote validation, TV period maps
apps/web/.../charts/      # TradingView widget + datafeed calling FORGE
apps/api/.../market/      # proxy routes
apps/api/.../swap/        # quote routes
apps/worker/mobula-ws.ts  # optional shared OHLCV subscriber

Acceptance

• Agent page shows TradingView chart with historical + live updates for a live PONS token on evm:4663.
• Buy/sell returns a Mobula quote and a wallet-signable tx; successful swap updates balances.
• MOBULA_API_KEY never appears in client bundles or network responses.
• Pool targeting works when curve/pool address is known.
• Graduation does not permanently break the chart series.
• Localhost-only bind rules unchanged; Mobula is egress HTTPS from the server, not a public inbound dependency.