docs | flybot

## introduction

flybot spawns fly agents that trade Robinhood Chain for you. each fly runs a simulated fly-neuron brain: sensory neurons read the market, integrate-and-fire interneurons accumulate charge, and a motor neuron fires BUY, SELL, HOLD, YES or NO. every fly has its own evm wallet on Robinhood Chain (chain id 4663) and streams each fill live over sockets.

flies start on paper: real prices, simulated fills, one ETH of play balance. live execution exists, is gated twice, and spends real ETH. see paper vs live before you turn it on.

## quickstart

1. /connect · connect on Robinhood Chain
wallet, twitter or email. twitter and email get an embedded wallet on the same chain.
2. /agents/new · spawn a fly
name it, pick senses (tokens, prediction markets), antennae sensitivity, and optional signal sources. it hatches with a genome and a wallet.
3. /agents/[id] · watch it think
the neuron trace panel shows the last decision. fills stream in as they happen. owners see the wallet panel and the execution switch.

SPAWN A FLY →

## neuron model

a fly brain is three layers of leaky integrate-and-fire neurons. each tick the fly samples its senses, converts each reading to a potential between 0 and 1, pushes charge through weighted synapses, and fires whichever motor neuron crosses threshold first. nothing fires, the fly HOLDs.

sensory      inter        motor
momentum ─┐
volume   ─┤  ┌─ i1 ─┐    ┌─ BUY
liquidity─┼──┤       ├────┤  SELL
odor     ─┤  └─ i2 ─┘    │  HOLD
odds     ─┘              └─ YES / NO

potential  ░░░░░░░░░░░░  0
           ████████▓░░░  0.7  ● fired

sensory neurons: momentum (price change over the last window), volume (24h volume against liquidity), liquidity (pool depth), odor (how often the token shows up in trending and signal sources), and market odds (implied probability drift on a prediction market).
interneurons: integrate-and-fire units with leak. they sum weighted sensory input over several ticks, so a single spike of volume does not move the fly; a pattern does.
motor neurons: BUY, SELL, HOLD for tokens. YES, NO for markets. the winner sets the fill type; its potential becomes the confidence you see on every trade.
antennae (risk): low raises the firing threshold and shrinks position size. high lowers it and sizes up. medium is the default.

## senses

senses decide which sensory neurons exist. a fly with only the tokens sense never sees a market and never fires YES or NO.

tokens: uniswap v3 pools on Robinhood Chain via GeckoTerminal. the fly ranks trending pools, reads 24h candles and pool depth, and trades the base token against ETH. motor: BUY, SELL.
markets: binary prediction markets from polymarket, kalshi and limitless. the odds neuron watches implied probability and volume. motor: YES, NO. paper only today: market fills are simulated at the venue price.
signal sources: optional x handles and telegram channels. mentions feed the odor neuron. leave blank and the fly relies on ambient market signal.

## genome and species

every fly hatches with a genome: the synapse weights, leak rates, thresholds and sizing curve for its brain, seeded from the spawn settings plus randomness. the genome hashes to a species name so related flies read as a family. owners can read the full genome from the brain endpoint; everyone else gets the species.

## paper vs live

paper: default. real prices from GeckoTerminal and the venues, simulated fills, ledger balance in wei. nothing leaves the wallet. good for watching a genome for a week before you trust it.
live: the fly signs Uniswap v3 swaps (SwapRouter02) from its own wallet on Robinhood Chain. gas is paid in ETH. every fill has a txHash and links to the explorer. losses are real.
gates: live is refused unless the operator runs the server with MONEY_ENABLED=true and TRADING_LIVE=true. even then, each fly must be switched to live by its owner from the settings menu. the switch endpoint returns 409 while the gates are closed. agent keys are stored encrypted (aes-256-gcm) and never leave the server.

## funding a fly

a paper fly needs nothing. a live fly needs ETH in its wallet for gas and for the swaps it fires. open your fly, copy the address from the wallet panel, and send ETH on Robinhood Chain to it.

chain      Robinhood Chain (arbitrum orbit l2)
chain id   4663
currency   ETH (18 decimals)
rpc        https://rpc.mainnet.chain.robinhood.com
explorer   https://robinhoodchain.blockscout.com
USDG       0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168
WETH       0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73

USDG is the dollar stable on the chain. the wallet panel shows both ETH and USDG balances read live from the rpc. there is no withdraw button yet; keep the amount you send to a fly at what you are comfortable leaving there.

## venues

uniswap v3: the token dex on Robinhood Chain. pools are discovered through GeckoTerminal's robinhood network. fee tiers 0.01, 0.05, 0.3 and 1 percent.
geckoterminal: trending pools, 24h candles, pool depth. also the chart embed on token pages.
dexscreener: secondary token metadata and price fallback. every token page links out to it.
polymarket: binary markets, gamma api. yes and no as 0..1 prices.
kalshi: regulated event contracts. yes price from the last trade.
limitless: onchain binary markets. quoted from the amm.

## api reference

everything the site shows is public json under /api. owner routes take Authorization: Bearer <privy token>.

GET/api/trending

trending uniswap v3 pools on Robinhood Chain via GeckoTerminal.

→ { tokens: Token[], ethPriceUsd, fetchedAt }

GET/api/tokens/:address

one token with 24 hourly closes. 404 if not sensed.

→ { token: Token & { sparkline: number[] }, ethPriceUsd }

GET/api/eth-price

eth/usd from chainlink on chain, dexscreener fallback.

→ { ethPriceUsd, source, fetchedAt }

GET/api/markets

prediction markets across polymarket, kalshi and limitless.

→ { markets: Market[], fetchedAt, venues }

GET/api/markets/:venue/:externalId

one market with its resolution text when the venue provides it.

→ { market: Market & { description? } }

GET/api/stats

platform counters for the landing page.

→ { agents, trades, tradesLast5m, liveAgents, marketsWatched, tokensWatched }

GET/api/transactions/recent?limit=

latest fills across public flies.

→ { transactions: TxPayload[] }

GET/api/transactions/:id

one fill. private flies require the owner token.

→ TxPayload

GET/api/agents

public flies. add ?mine=1 with a bearer token for yours.

→ Agent[]

POST/api/agentsbearer

spawn a fly. body: { name, description, avatarUrl, riskLevel, mode, senses, sources? }

→ Agent

GET/api/agents/:id

one fly. owners see the full wallet and genome; others get a masked wallet and { species }.

→ Agent

PATCH/api/agents/:idbearer

rename, describe, pause, archive.

→ Agent

GET/api/agents/:id/transactions

fills for one fly.

→ { transactions: TxPayload[] }

GET/api/agents/:id/balance-history

equity points for the chart.

→ { points: BalancePoint[] }

GET/api/agents/:id/brain

genome plus the last neuron trace.

→ { genome, lastTrace }

POST/api/agents/:id/executionbearer, owner

body { execution: 'paper' | 'live' }. live returns 409 unless MONEY_ENABLED and TRADING_LIVE are both true on the server.

→ { execution }

GET/api/agents/:id/walletbearer, owner

the fly's address with live on-chain ETH and USDG balances.

→ { address, ethBalanceWei, usdgBalance, explorerUrl }

## response shapes

Agent

id: string; stable fly id.
name: string; display name.
wallet_address: 0x…; evm address on Robinhood Chain. masked for non-owners.
execution: paper | live; paper simulates fills at real prices. live signs swaps.
balance_wei: string; ledger balance in wei. also balance_eth and balance_usd.
risk_level: low | medium | high; antennae sensitivity: the firing threshold.
senses: string[]; subset of tokens, markets.
genome: object; per-fly weights and species. owners only; public gets { species }.
profit_loss_pct: number; pnl versus initial_balance_wei.

TxPayload

id: string; fill id.
agentId: string; the fly.
type: BUY | SELL | YES | NO; motor neuron that fired.
tokenAddress: 0x… | null; token for BUY / SELL.
marketVenue: polymarket | kalshi | limitless | null; venue for YES / NO.
marketSlug: string | null; venue external id for the market page.
price: number; usd per token, or probability 0..1 for markets.
totalUsd: number; notional.
ethAmount: number; eth spent or received.
txHash: string | null; present only for live fills. links to the explorer.
neuron: { fired, motor, confidence }; trace summary for the fill.

Market

id: string; venue:externalId.
venue: polymarket | kalshi | limitless; where the odds come from.
yesPrice / noPrice: number 0..1; implied probability per side.
volume24h / volumeTotal / liquidity: number; usd.
endDate: string | null; iso timestamp when known.
url: string; the venue page.

Token

address: 0x…; erc20 on Robinhood Chain.
priceUsd / change24hPct: number; spot and 24h change.
volume24hUsd / liquidityUsd / marketCapUsd: number | null; pool stats.
poolAddress: 0x… | null; uniswap v3 pool used for the chart embed.
url: string; geckoterminal pool page.

## socket events

the api also runs socket.io on the same origin. subscribe with subscribe:global for every public fill or subscribe:agent with an agent id (and a bearer token for private flies).

tx:new          TxPayload plus agentName, agentAvatar and neuron
balance:update  { agentId, transactionId, balanceWei, balanceEth, balanceUsd }

## faq

is this an ai agent?: no llm decides trades. the brain is a small spiking network with fixed structure and a per-fly genome. the chat on a fly's page is a separate model that reads the fly's state and explains it.
can a fly lose money on paper?: the ledger can go down, which is the point. nothing on chain moves.
why is live disabled?: the operator has not set MONEY_ENABLED and TRADING_LIVE. until both are true the execution switch returns 409 and every fly stays on paper.
who can see my fly?: personal flies are visible to their owner only, including trades and the trace. public flies are listed and anyone can chat with them. wallet addresses are masked for non-owners.
what happens if a venue is down?: the markets response reports per-venue status. the odds neuron sees no input from a venue that is down and the fly does not fire on it.
can i export my fly's key?: not from the ui. keys are encrypted at rest with AGENT_KEY_SECRET on the server. treat a live fly's wallet as a hot wallet with a budget.

SPAWN A FLY →MARKETS →DASHBOARD →

## introduction

flies start on paper: real prices, simulated fills, one ETH of play balance. live execution exists, is gated twice, and spends real ETH. see paper vs live before you turn it on.

## quickstart

1. /connect · connect on Robinhood Chain
wallet, twitter or email. twitter and email get an embedded wallet on the same chain.
2. /agents/new · spawn a fly
name it, pick senses (tokens, prediction markets), antennae sensitivity, and optional signal sources. it hatches with a genome and a wallet.
3. /agents/[id] · watch it think
the neuron trace panel shows the last decision. fills stream in as they happen. owners see the wallet panel and the execution switch.

SPAWN A FLY →

## neuron model

sensory      inter        motor
momentum ─┐
volume   ─┤  ┌─ i1 ─┐    ┌─ BUY
liquidity─┼──┤       ├────┤  SELL
odor     ─┤  └─ i2 ─┘    │  HOLD
odds     ─┘              └─ YES / NO

potential  ░░░░░░░░░░░░  0
           ████████▓░░░  0.7  ● fired

sensory neurons: momentum (price change over the last window), volume (24h volume against liquidity), liquidity (pool depth), odor (how often the token shows up in trending and signal sources), and market odds (implied probability drift on a prediction market).
interneurons: integrate-and-fire units with leak. they sum weighted sensory input over several ticks, so a single spike of volume does not move the fly; a pattern does.
motor neurons: BUY, SELL, HOLD for tokens. YES, NO for markets. the winner sets the fill type; its potential becomes the confidence you see on every trade.
antennae (risk): low raises the firing threshold and shrinks position size. high lowers it and sizes up. medium is the default.

## senses

senses decide which sensory neurons exist. a fly with only the tokens sense never sees a market and never fires YES or NO.

tokens: uniswap v3 pools on Robinhood Chain via GeckoTerminal. the fly ranks trending pools, reads 24h candles and pool depth, and trades the base token against ETH. motor: BUY, SELL.
markets: binary prediction markets from polymarket, kalshi and limitless. the odds neuron watches implied probability and volume. motor: YES, NO. paper only today: market fills are simulated at the venue price.
signal sources: optional x handles and telegram channels. mentions feed the odor neuron. leave blank and the fly relies on ambient market signal.

## genome and species

## paper vs live

paper: default. real prices from GeckoTerminal and the venues, simulated fills, ledger balance in wei. nothing leaves the wallet. good for watching a genome for a week before you trust it.
live: the fly signs Uniswap v3 swaps (SwapRouter02) from its own wallet on Robinhood Chain. gas is paid in ETH. every fill has a txHash and links to the explorer. losses are real.
gates: live is refused unless the operator runs the server with MONEY_ENABLED=true and TRADING_LIVE=true. even then, each fly must be switched to live by its owner from the settings menu. the switch endpoint returns 409 while the gates are closed. agent keys are stored encrypted (aes-256-gcm) and never leave the server.

## funding a fly

a paper fly needs nothing. a live fly needs ETH in its wallet for gas and for the swaps it fires. open your fly, copy the address from the wallet panel, and send ETH on Robinhood Chain to it.

chain      Robinhood Chain (arbitrum orbit l2)
chain id   4663
currency   ETH (18 decimals)
rpc        https://rpc.mainnet.chain.robinhood.com
explorer   https://robinhoodchain.blockscout.com
USDG       0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168
WETH       0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73

## venues

uniswap v3: the token dex on Robinhood Chain. pools are discovered through GeckoTerminal's robinhood network. fee tiers 0.01, 0.05, 0.3 and 1 percent.
geckoterminal: trending pools, 24h candles, pool depth. also the chart embed on token pages.
dexscreener: secondary token metadata and price fallback. every token page links out to it.
polymarket: binary markets, gamma api. yes and no as 0..1 prices.
kalshi: regulated event contracts. yes price from the last trade.
limitless: onchain binary markets. quoted from the amm.

## api reference

everything the site shows is public json under /api. owner routes take Authorization: Bearer <privy token>.

GET/api/trending

trending uniswap v3 pools on Robinhood Chain via GeckoTerminal.

→ { tokens: Token[], ethPriceUsd, fetchedAt }

GET/api/tokens/:address

one token with 24 hourly closes. 404 if not sensed.

→ { token: Token & { sparkline: number[] }, ethPriceUsd }

GET/api/eth-price

eth/usd from chainlink on chain, dexscreener fallback.

→ { ethPriceUsd, source, fetchedAt }

GET/api/markets

prediction markets across polymarket, kalshi and limitless.

→ { markets: Market[], fetchedAt, venues }

GET/api/markets/:venue/:externalId

one market with its resolution text when the venue provides it.

→ { market: Market & { description? } }

GET/api/stats

platform counters for the landing page.

→ { agents, trades, tradesLast5m, liveAgents, marketsWatched, tokensWatched }

GET/api/transactions/recent?limit=

latest fills across public flies.

→ { transactions: TxPayload[] }

GET/api/transactions/:id

one fill. private flies require the owner token.

→ TxPayload

GET/api/agents

public flies. add ?mine=1 with a bearer token for yours.

→ Agent[]

POST/api/agentsbearer

spawn a fly. body: { name, description, avatarUrl, riskLevel, mode, senses, sources? }

→ Agent

GET/api/agents/:id

one fly. owners see the full wallet and genome; others get a masked wallet and { species }.

→ Agent

PATCH/api/agents/:idbearer

rename, describe, pause, archive.

→ Agent

GET/api/agents/:id/transactions

fills for one fly.

→ { transactions: TxPayload[] }

GET/api/agents/:id/balance-history

equity points for the chart.

→ { points: BalancePoint[] }

GET/api/agents/:id/brain

genome plus the last neuron trace.

→ { genome, lastTrace }

POST/api/agents/:id/executionbearer, owner

body { execution: 'paper' | 'live' }. live returns 409 unless MONEY_ENABLED and TRADING_LIVE are both true on the server.

→ { execution }

GET/api/agents/:id/walletbearer, owner

the fly's address with live on-chain ETH and USDG balances.

→ { address, ethBalanceWei, usdgBalance, explorerUrl }

## response shapes

Agent

id: string; stable fly id.
name: string; display name.
wallet_address: 0x…; evm address on Robinhood Chain. masked for non-owners.
execution: paper | live; paper simulates fills at real prices. live signs swaps.
balance_wei: string; ledger balance in wei. also balance_eth and balance_usd.
risk_level: low | medium | high; antennae sensitivity: the firing threshold.
senses: string[]; subset of tokens, markets.
genome: object; per-fly weights and species. owners only; public gets { species }.
profit_loss_pct: number; pnl versus initial_balance_wei.

TxPayload

id: string; fill id.
agentId: string; the fly.
type: BUY | SELL | YES | NO; motor neuron that fired.
tokenAddress: 0x… | null; token for BUY / SELL.
marketVenue: polymarket | kalshi | limitless | null; venue for YES / NO.
marketSlug: string | null; venue external id for the market page.
price: number; usd per token, or probability 0..1 for markets.
totalUsd: number; notional.
ethAmount: number; eth spent or received.
txHash: string | null; present only for live fills. links to the explorer.
neuron: { fired, motor, confidence }; trace summary for the fill.

Market

id: string; venue:externalId.
venue: polymarket | kalshi | limitless; where the odds come from.
yesPrice / noPrice: number 0..1; implied probability per side.
volume24h / volumeTotal / liquidity: number; usd.
endDate: string | null; iso timestamp when known.
url: string; the venue page.

Token

address: 0x…; erc20 on Robinhood Chain.
priceUsd / change24hPct: number; spot and 24h change.
volume24hUsd / liquidityUsd / marketCapUsd: number | null; pool stats.
poolAddress: 0x… | null; uniswap v3 pool used for the chart embed.
url: string; geckoterminal pool page.

## socket events

the api also runs socket.io on the same origin. subscribe with subscribe:global for every public fill or subscribe:agent with an agent id (and a bearer token for private flies).

tx:new          TxPayload plus agentName, agentAvatar and neuron
balance:update  { agentId, transactionId, balanceWei, balanceEth, balanceUsd }

## faq

is this an ai agent?: no llm decides trades. the brain is a small spiking network with fixed structure and a per-fly genome. the chat on a fly's page is a separate model that reads the fly's state and explains it.
can a fly lose money on paper?: the ledger can go down, which is the point. nothing on chain moves.
why is live disabled?: the operator has not set MONEY_ENABLED and TRADING_LIVE. until both are true the execution switch returns 409 and every fly stays on paper.
who can see my fly?: personal flies are visible to their owner only, including trades and the trace. public flies are listed and anyone can chat with them. wallet addresses are masked for non-owners.
what happens if a venue is down?: the markets response reports per-venue status. the odds neuron sees no input from a venue that is down and the fly does not fire on it.
can i export my fly's key?: not from the ui. keys are encrypted at rest with AGENT_KEY_SECRET on the server. treat a live fly's wallet as a hot wallet with a budget.

SPAWN A FLY →MARKETS →DASHBOARD →

flies, neurons and Robinhood Chain

## introduction

## quickstart

## neuron model

## senses

## genome and species

## paper vs live

## funding a fly

## venues

## api reference

## response shapes

## socket events

## faq

flies, neurons and Robinhood Chain

## introduction

## quickstart

## neuron model

## senses

## genome and species

## paper vs live

## funding a fly

## venues

## api reference

## response shapes

## socket events

## faq