Overview Getting Started Contracts & ABI Integration Guide HTTP API ERC-8056 Stock Standard Liquidity & Reserves Keeper Node Guide Error Codes & Debugging FAQ & Risks

Getting Started

From cloning the repository to running a full local demo workspace (web app, keeper, and smart contracts) in under five minutes. No live API keys are required in mock mode.

Repository Structure

Longbow is set up as a monorepo using pnpm workspaces:

Monorepo layout

longbow/
  apps/
    web/                   # Next.js web application (landing, app, docs, APIs)
  packages/
    contracts/             # Solidity smart contracts, scripts, and Foundry tests
    keeper/                # Node.js keeper bot for filling active orders
    shared/                # Core token registries, ABI types, and shared src
  package.json             # pnpm root workspace config
  pnpm-workspace.yaml      # Workspace package mapping

Prerequisites

Node.js >= 18.17 and pnpm >= 9
Foundry (forge) - only needed for compiling or testing smart contracts
An injected browser wallet (MetaMask or Rabby) - only required for live blockchain mode

1 · Install & Run

Clone the fork, install dependencies, and launch both the web application and the keeper node:

terminal

git clone https://github.com/longbowtrade/longbow.git && cd longbow
pnpm install

# 1 - Run the Next.js web app (Landing + Terminal App + APIs + Docs)
pnpm --filter web dev       # Starts on http://localhost:3000 (fallback to 3001)

# 2 - Run the Keeper Node (watches and executes active orders)
pnpm --filter keeper start  # Polls database/API every 15s

Mock mode is enabled by default (NEXT_PUBLIC_USE_MOCKS=true). Prices, reserves, user holdings, and execution logs are simulated deterministically inside the browser/API, meaning the entire placement, polling, and execution loop works completely offline without network requirements.

2 · Environment Settings

.env

cp .env.example .env
# then set what you need:
NEXT_PUBLIC_CHAIN_ID=46630        # 4663 for mainnet, 46630 for testnet
NEXT_PUBLIC_USE_MOCKS=true        # Set to false to disable mock simulation and read from L2
FINNHUB_API_KEY=                  # Key for off-chain stock quotes (finnhub.io, free tier)
ALPHAVANTAGE_API_KEY=             # Fallback stock quote key
EXECUTOR_ADDRESS=                 # Contract address of your deployed LongbowExecutor
KEEPER_PRIVATE_KEY=               # Funded keeper wallet private key (required for live L2 executions)

3 · Compiling & Testing Contracts

Solidity contracts live inside the packages/contracts folder. Compile and run unit tests using Foundry:

terminal

cd packages/contracts
forge build           # Compile executor contracts and generate ABI
forge test -vv        # Run contract test suites (triggers, DCA logic, slippage guards)

4 · Deploying Contracts

terminal

# Deploy the demo environment (mock pools + seed tokens) to Robinhood Testnet
forge script script/SeedDemo.s.sol \\
  --rpc-url robinhood_testnet --broadcast --private-key $DEPLOYER_KEY

# Deploy the production executor against mainnet Uniswap V2 Router
ROUTER=0x89e5db8b5aa49aa85ac63f691524311aeb649eba \\
forge script script/Deploy.s.sol \\
  --rpc-url robinhood_mainnet --broadcast --private-key $DEPLOYER_KEY

Verify that you are using the correct network credentials. The testnet RPC and faucet can be found on faucet.testnet.chain.robinhood.com. Testnet chain ID is 46630.

Setup Troubleshooting

Port Conflicts — If port 3000 is in use, Next.js dev server will automatically start on http://localhost:3001. The app will adjust itself, but make sure to check terminal logs.
Keeper fails to execute — Verify that you have funded the keeper's private key address with native L2 ETH to pay for transaction gas, and that USE_MOCKS=false is set on the keeper terminal if you're trying to execute real swaps.