# FlashLoanLab

> Flash loan arbitrage discovery and execution platform. FlashLoanLab scans EVM chains (Base, Arbitrum, Ethereum) and Solana for profitable arbitrage opportunities, simulates them on mainnet forks, scores them, and enables both manual and automated execution via Aave V3 flash loans with an on-chain revenue share model.

## Product

FlashLoanLab is a DeFi arbitrage platform with four components:
- **Scanner**: continuously scans Uniswap V2/V3 pools for price discrepancies across chains
- **Simulator**: validates opportunities on Hardhat mainnet forks before live execution
- **Executor**: submits `FlashLoanReceiver.executeArbitrage()` transactions with Aave V3 flash loans
- **Auto Trader**: BullMQ worker that executes high-score (≥90/100) opportunities automatically

The smart contract (`FlashLoanReceiver.sol`) splits profits on-chain: platform fee is deducted before funds return to the owner's wallet. Users never need to pre-fund positions — flash loans are repaid within a single transaction.

## Revenue Model

Platform keeps a percentage of profitable trades only. No subscription fees.

| Plan       | User keeps | Platform fee |
|------------|-----------|--------------|
| Free       | 75%       | 25%          |
| Pro        | 80%       | 20%          |
| Elite      | 85%       | 15%          |
| Enterprise | 90%       | 10%          |

## API

Base URL: `https://flashloanlab.com/api`

All authenticated endpoints require `Authorization: Bearer <session_token>` header.

### Authentication

- `POST /auth/register` — create account (`{ email, password, name? }`) → `{ user, token }`
- `POST /auth/login` — sign in (`{ email, password }`) → `{ user, token }`
- `POST /auth/logout` — invalidate session
- `POST /auth/forgot-password` — request reset link (`{ email }`)
- `POST /auth/reset-password` — set new password (`{ token, password }`)

### Opportunities

- `GET /opportunities` — list active arbitrage opportunities (authenticated)
- `GET /opportunities/:id` — single opportunity detail

### Execution

- `POST /execute/:opportunityId/prepare` — validate and prepare transaction params for `FlashLoanReceiver.executeArbitrage()`
- `POST /execute/:executionId/receipt` — record tx hash and final status after on-chain execution
- `GET /execute/history` — user's execution history

### Auto Trading

- `GET /auto-trading/settings` — get risk limits and status
- `PATCH /auto-trading/settings` — update risk limits
- `POST /auto-trading/arm` — enable auto execution
- `POST /auto-trading/disarm` — disable auto execution
- `POST /auto-trading/emergency-stop` — immediately halt all activity
- `GET /auto-trading/status` — today's stats
- `GET /auto-trading/logs` — today's activity log
- `POST /auto-trading/wallet` — register encrypted trading wallet
- `DELETE /auto-trading/wallet` — remove trading wallet

### Simulator

- `POST /simulate` — run a simulation on a Hardhat mainnet fork

### Earnings

- `GET /earnings/summary` — lifetime profit summary
- `GET /earnings/history` — settlement history

### Safety

- `GET /safety` — get safety settings
- `PATCH /safety` — update safety settings

### Tokens

- `GET /tokens` — list tracked tokens
- `GET /tokens/:address/risk` — GoPlus security risk report for a token address

### Solana (when FEATURE_SOLANA=true)

- `GET /solana/scan` — scan Solana token pairs via Jupiter V6 quotes
- `GET /solana/tokens` — list tracked Solana tokens
- `GET /solana/health` — Solana RPC health

### System

- `GET /health` — API liveness check → `{ status: "ok", version, timestamp }`
- `GET /health/ready` — readiness probe (checks DB)
- `GET /health/status` — detailed health of all services (DB, Redis, RPCs)

### Admin (ADMIN role required)

- `GET /admin/users` — list all users
- `PUT /admin/users/:userId/plan` — change user plan
- `GET /admin/revenue-share/defaults` — plan fee defaults
- `GET /admin/revenue-share/users` — per-user overrides
- `PUT /admin/revenue-share/users/:userId` — set user fee override
- `DELETE /admin/revenue-share/users/:userId` — remove override
- `GET /admin/revenue-share/settlements` — recent profit settlements
- `GET /admin/settings` — system settings
- `PUT /admin/settings/:key` — update a system setting

## Smart Contract

`FlashLoanReceiver.sol` is deployed on Base, Arbitrum, and Ethereum mainnet.

Key functions:
- `executeArbitrage(ExecuteParams p)` — onlyOwner, initiates Aave V3 `flashLoanSimple`, executes arbitrage hops, splits profit on-chain
- `executeOperation(...)` — Aave callback, validates `msg.sender == _authorizedPool`, executes swaps
- `emergencyWithdraw(address token, address to)` — onlyOwner, rescue stuck tokens
- `rescueEth(address payable to)` — onlyOwner, rescue stuck ETH

`MAX_FEE_BPS = 3000` (30%) is a hard cap enforced in the contract.

## Chains Supported

| Chain     | Chain ID | Flash Loan Provider | DEXes             |
|-----------|----------|---------------------|-------------------|
| Base      | 8453     | Aave V3             | Uniswap V2 & V3   |
| Arbitrum  | 42161    | Aave V3             | Uniswap V2 & V3   |
| Ethereum  | 1        | Aave V3             | Uniswap V2 & V3   |
| Solana    | —        | Simulator only      | Jupiter V6 quotes |

## Optional: llms-full.txt

[Full API reference with request/response schemas](https://flashloanlab.com/llms-full.txt)