API Documentation

Overview

The FlashLoanLab API is a JSON REST API served by a Fastify backend. It handles authentication, opportunity discovery, trade execution, auto-trading configuration, and admin management.

All timestamps are ISO 8601 strings in UTC. Chain IDs are integers (e.g. 8453). Token amounts are strings representing the raw value in the token's smallest unit (wei for ETH-based tokens).

Supported chains: Base (8453), Arbitrum One (42161), Ethereum (1), Optimism (10), Polygon (137). Each chain scans Uniswap V3 plus chain-specific DEXes: SushiSwap V3 (Base, Arbitrum, Ethereum), QuickSwap V3 (Polygon), SushiSwap V2 (Arbitrum, Optimism, Polygon), QuickSwap V2 (Polygon), Camelot V2 (Arbitrum), and Uniswap V2 (Ethereum).

Request format

POST /auth/login
Content-Type: application/json
Authorization: Bearer <session_token>   // required on authenticated routes

{
  "email": "user@example.com",
  "password": "hunter2"
}

Response envelope

Successful responses return the data directly. Errors use:

{
  "error": "Invalid credentials",   // human-readable message
  "code":  "UNAUTHORIZED"           // optional machine-readable code
}

Authentication

Sessions are Bearer tokens returned on login or register. Pass the token in the Authorization header on every authenticated request. Tokens do not expire on their own — call POST /auth/logout to invalidate.

Register

POST /auth/register
{
  "email":    "alice@example.com",
  "password": "at_least_8_chars",
  "name":     "Alice"             // optional
}

→ 201
{
  "user":  { "id": "...", "email": "alice@example.com", "name": "Alice", "role": "USER", "plan": "FREE" },
  "token": "fll_tok_..."
}

Login

POST /auth/login
{
  "email":    "alice@example.com",
  "password": "at_least_8_chars"
}

→ 200
{
  "user":  { "id": "...", "email": "alice@example.com", "role": "USER", "plan": "FREE" },
  "token": "fll_tok_..."
}

Reset password

// Step 1 — request a reset link
POST /auth/forgot-password
{ "email": "alice@example.com" }
→ 200 { "message": "If that address exists, a reset email has been sent." }

// Step 2 — set new password using token from email link
POST /auth/reset-password
{ "token": "<token_from_email>", "password": "new_password" }
→ 200 { "message": "Password updated successfully." }

Opportunities

Opportunities are arbitrage price discrepancies detected by the scanner. They include a confidence score (0–100), estimated profit, simulation result, and token safety data.

Opportunity object

{
  "id":               "opp_...",
  "chainId":          8453,
  "chain":            { "chainId": 8453, "name": "Base", "shortName": "Base" },
  "strategyType":     "DEX_ARBITRAGE",
  "status":           "ACTIVE",
  "borrowToken":      { "address": "0x42...06", "symbol": "WETH", "decimals": 18, "tier": 1 },
  "borrowAmount":     "1000000000000000000",   // wei string
  "borrowAmountUsd":  3400.00,

  // ── Financials (all USD) ───────────────────────────────────────────────────
  "grossProfitUsd":   18.32,   // spread profit; DEX pool fees already deducted
  "flashLoanFeeUsd":   1.70,   // Aave V3 0.05% of borrow
  "gasCostUsd":        2.10,   // estimated fast gas
  "dexFeesUsd":        6.80,   // informational only — already reflected in grossProfitUsd
  "netProfitUsd":     13.22,   // grossProfit − flashLoanFee − gas − slippage reserve
  "profitPct":         0.389,  // netProfitUsd / borrowAmountUsd * 100
  // personalised to caller's plan (requires auth):
  "userProfitUsd":     9.92,   // netProfitUsd × (1 − platformFeePct/100)
  "platformFeeUsd":    3.30,   // netProfitUsd × platformFeePct/100
  "platformFeePct":   25.0,    // caller's plan rate (Free=25, Pro=20, Elite=15, Enterprise=10)

  "score":            92,
  "mevRisk":          "LOW",
  "simulationStatus": "PASSED",
  "isLiveEligible":   true,
  "isAutoEligible":   true,
  "createdAt":        "2025-11-01T12:34:56Z",
  "expiresAt":        "2025-11-01T12:35:26Z"
}

minProfitPct filter

Pass ?minProfitPct=0.05to only return opportunities where net profit is at least 0.05% of the borrow amount. If omitted and the caller is authenticated, the API auto-applies the user's saved minProfitPct from Safety Settings. Example: 0.05% on a $50k borrow = $25 minimum net profit.

Execution

Execution is a two-step process. First, call /execute/:id/prepare to get the transaction parameters for FlashLoanReceiver.executeArbitrage(). Sign and broadcast the transaction yourself (MetaMask / wagmi). Then call /execute/:executionId/receipt with the tx hash so the platform can confirm the settlement on-chain.

Prepare response

POST /execute/opp_.../prepare
→ 200
{
  "executionId": "exec_...",
  "contractAddress": "0x...",   // FlashLoanReceiver deployed on this chain
  "params": {
    "pool":         "0x...",    // Aave V3 pool address
    "asset":        "0x...",    // borrow token
    "amount":       "1000000000000000000",
    "buyDex":       "0x...",
    "sellDex":      "0x...",
    "feeBps":       2000,       // platform fee in basis points (20%)
    "deadline":     1730462096
  },
  "estimatedGas": "420000",
  "gasPrice":     "50000000"    // in wei, current fast price
}

Receipt

POST /execute/exec_.../receipt
{ "txHash": "0x..." }
→ 200 { "status": "confirmed", "profit": "3820000000000000" }

Auto Trading

Auto Trading runs a background worker that fires on opportunities scoring ≥90. It requires a trading wallet to be registered. All safety limits are enforced server-side — the bot will pause itself if any threshold is breached.

Settings object

{
  "enabled":           false,
  "mode":              "paper",      // "paper" | "mainnet"
  "minScore":          90,           // only fire on opps scoring >= this
  "minProfitUsd":      5,
  "maxDailyLossUsd":   100,
  "maxTradesPerDay":   50,
  "maxFailedTxs":      3,
  "hasWallet":         true,
  "walletAddress":     "0x..."       // derived from stored key, never the key itself
}

Registering a trading wallet

The private key is encrypted with AES-256-GCM server-side before storage. It is never logged, never returned by any API endpoint, and never accessible from the frontend.

POST /auto-trading/wallet
{ "privateKey": "0x..." }
→ 200 { "walletAddress": "0x...", "message": "Wallet registered securely." }

Earnings

The platform deducts a percentage-based fee from each profitable trade, determined by the user's plan. Use these endpoints to inspect fee config, preview profit splits, change plan, and view settlement history.

Plan change

POST /earnings/plan
{ "plan": "PRO" }   // FREE | PRO | ELITE | ENTERPRISE

→ 200
{
  "plan":           "PRO",
  "platformFeePct": 20,
  "monthlyFeeUsd":  0
}

Safety & Logs

Safety controls gate live and auto-trading execution. Audit logs record account activity (logins, settings changes, executions). Risk events capture safety-limit breaches.

Safety settings object

{
  "liveExecutionEnabled":      false,
  "minScoreLive":              70,     // min score for manual live execution
  "minScoreAuto":              90,     // min score for auto trading
  "minProfitPct":              0.05,   // min net profit % of borrow to surface opportunities
                                       // (0 = no filter; e.g. 0.05 = $25 on a $50k borrow)
  "maxBorrowUsd":              50000,
  "maxSlippagePct":            1.5,
  "maxGasGwei":                50,
  "maxDailyLossUsd":           500,
  "requireResimulation":       true,
  "requireWalletConfirmation": true,
  "emergencyStopActive":       false
}

Errors & Rate Limits

HTTP status codes

Rate limits

The API is rate-limited per IP: 100 requests per minute for most routes, 10 requests per minute for auth endpoints. Exceeding the limit returns 429 with a Retry-After header.