API Reference

Technical documentation for developers integrating with LNCHR APIs. This covers authentication, bot management endpoints, and webhook events. All amounts and addresses are Ethereum mainnet.

API Access

The LNCHR API is currently for internal use by the web dashboard. Public API access with API keys may be available in the future.

Authentication

Overview

LNCHR uses wallet-based authentication with JWT tokens. Users prove wallet ownership by signing a human-readable message with their Ethereum wallet (EIP-191 personal_sign), then receive a JWT for subsequent API calls.

Authentication Flow

Request a nonce message to sign
Sign the message with your Ethereum wallet
Submit the signature to receive a JWT token
Include the JWT in the Authorization header for authenticated requests

Step 1: Get Nonce

POST /api/bot/auth
Content-Type: application/json

{
  "action": "nonce",
  "wallet": "0xYourChecksumAddress..."
}

Response:
{
  "nonce": "LNCHR Bot Authentication\n\nAddress: 0x...\nTimestamp: ...\nNonce: ...\n\nSign this message to verify your wallet ownership."
}

Step 2: Verify Signature

POST /api/bot/auth
Content-Type: application/json

{
  "action": "verify",
  "wallet": "0xYourChecksumAddress...",
  "signature": "0x<65-byte ECDSA signature>",
  "message": "The nonce message you signed"
}

Response:
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "user-uuid",
    "wallet": "0xYourChecksumAddress..."
  }
}

Step 3: Use Token

GET /api/bot/bots
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response:
{
  "bot": { ... }
}

Token Validation

GET /api/bot/auth
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response:
{
  "valid": true,
  "user": {
    "id": "user-uuid",
    "wallet": "0x..."
  }
}

Bot Endpoints

Get Bot

Retrieve the current user's bot configuration and status.

GET /api/bot/bots
Authorization: Bearer <token>

Response:
{
  "bot": {
    "id": "bot-uuid",
    "status": "running" | "stopped" | "starting" | "stopping" | "error",
    "config": {
      "tradeAmountEth": 0.01,
      "holdDurationMinutes": 6,
      "minMarketCap": 27000,
      "maxMarketCap": 59000
    },
    "stats": {
      "totalTrades": 42,
      "openTrades": 1,
      "closedTrades": 41,
      "winningTrades": 25,
      "losingTrades": 16,
      "totalPnl": 0.15,
      "totalFeesPaid": 0.004,
      "winRate": 61
    },
    "wallet": {
      "address": "0x...",
      "balance": 0.123
    },
    "feePercent": 1.0,
    "createdAt": "2026-04-11T10:30:00Z",
    "updatedAt": "2026-04-11T12:45:00Z"
  }
}

Create Bot

Create a new bot for the authenticated user.

POST /api/bot/bots
Authorization: Bearer <token>
Content-Type: application/json

{}  // No body required; optional { config: {...} }

Response:
{
  "success": true,
  "bot": { ... },
  "message": "Bot created successfully! Deposit ETH to start trading."
}

Update Bot Settings

Update bot trading configuration. Bot must be stopped.

PATCH /api/bot/bots/config
Authorization: Bearer <token>
Content-Type: application/json

{
  "tradeAmountEth": 0.02,
  "holdDurationMinutes": 10,
  "minMarketCap": 10000,
  "maxMarketCap": 40000
}

Response:
{
  "success": true,
  "message": "Bot configuration updated",
  "config": { ... }
}

Start Bot

Start the trading bot. Provisions a Railway container on first start.

POST /api/bot/bots/start
Authorization: Bearer <token>

Response (first time):
{
  "success": true,
  "status": "starting",
  "message": "Bot is starting for the first time. This may take 3-5 minutes to build.",
  "containerId": "railway-service-id",
  "isFirstTime": true
}

Response (subsequent):
{
  "success": true,
  "status": "starting",
  "message": "Bot is resuming. This should only take a moment.",
  "containerId": "railway-service-id",
  "isResume": true
}

Stop Bot

Stop the running trading bot.

POST /api/bot/bots/stop
Authorization: Bearer <token>

Response:
{
  "success": true,
  "status": "stopped",
  "message": "Bot stopped successfully",
  "openTrades": 0
}

Get Trades

Retrieve trade history for the user's bot.

GET /api/bot/trades?status=all&limit=50&offset=0
Authorization: Bearer <token>

Query Parameters:
- status: "open" | "closed" | "all" (default: "all")
- limit: number (default: 50, max: 100)
- offset: number (default: 0)

Response:
{
  "trades": [
    {
      "id": 123,
      "tokenAddress": "0x...",         // 42-char hex
      "tokenName": "Doge Rocket",
      "tokenSymbol": "DGRKT",
      "status": "closed",
      "buy": {
        "price": 0.00000001234,
        "amountEth": 0.01,
        "txHash": "0x..."              // 66-char hex
      },
      "sell": {
        "price": 0.00000001456,
        "amountEth": 0.0118,
        "txHash": "0x..."
      },
      "pnl": 0.0018,
      "fee": {
        "percent": 1.0,
        "amountEth": 0.000118,
        "txHash": "0x..."
      },
      "createdAt": "2026-04-11T10:30:00Z",
      "closedAt": "2026-04-11T10:36:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Get Wallet

Get bot wallet address and live on-chain balance.

GET /api/bot/wallets
Authorization: Bearer <token>

Response:
{
  "wallet": {
    "address": "0x...",
    "balance": 0.123
  },
  "botStatus": "stopped"
}

Withdraw ETH

Withdraw ETH from the bot wallet. Bot must be stopped.

POST /api/bot/wallets/withdraw
Authorization: Bearer <token>
Content-Type: application/json

{
  "destinationWallet": "0x...",
  "amount": 0.05                // OR
  "percentage": 50              // one of: 25, 50, 75, 100
}

Response:
{
  "success": true,
  "txHash": "0x...",
  "amount": 0.05,
  "newBalance": 0.073,
  "destination": "0x...",
  "message": "Successfully withdrew 0.050000 ETH"
}

Webhook Events

The trading bot sends webhook events to the platform to report status and trade activity. These are internal webhooks used between the bot container and the platform.

Webhook Endpoint

POST /api/bot/webhook
Content-Type: application/json

{
  "botId": "bot-uuid",
  "secret": "BOT_WEBHOOK_SECRET",
  "event": "event_type",
  "data": { ... }
}

Event: bot_started

{ "event": "bot_started", "data": {} }

Event: bot_stopped

{ "event": "bot_stopped", "data": {} }

Event: bot_error

{
  "event": "bot_error",
  "data": { "error": "Human-readable error message" }
}

Event: trade_opened

Sent when the bot executes a Uniswap V2 buy.

{
  "event": "trade_opened",
  "data": {
    "tokenAddress": "0x...",
    "tokenName": "Doge Rocket",
    "tokenSymbol": "DGRKT",
    "buyPrice": 0.00000001234,
    "buyAmountEth": 0.01,
    "buyTxHash": "0x..."
  }
}

Event: trade_closed

Sent when the bot executes a Uniswap V2 sell and the fee transfer has settled.

{
  "event": "trade_closed",
  "data": {
    "tokenAddress": "0x...",
    "sellAmountEth": 0.0118,
    "sellTxHash": "0x...",
    "pnlEth": 0.0018,
    "feeAmountEth": 0.000118,
    "feeTxHash": "0x..."
  }
}

Error Handling

Error Response Format

{
  "error": "Human-readable error message"
}

// With additional details
{
  "error": "Insufficient balance",
  "currentBalance": 0.003,
  "requiredBalance": 0.012
}

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or expired token
404	Not Found - Resource doesn't exist
500	Server Error - Something went wrong

Environment Variables

For self-hosting or development, the following environment variables are required:

Platform (Next.js)

# Database
POSTGRES_URL=postgres://...

# Ethereum mainnet RPC
NEXT_PUBLIC_ETH_RPC_URL=https://eth.llamarpc.com

# Authentication
BOT_JWT_SECRET=random-secret-string

# Wallet Encryption
WALLET_ENCRYPTION_SECRET=random-32-char-secret

# Railway (Bot Hosting)
RAILWAY_API_TOKEN=railway-api-token
RAILWAY_PROJECT_ID=project-id
RAILWAY_ENVIRONMENT_ID=environment-id
RAILWAY_BOT_REPO=your-org/ethereum-trading-bot

# Bot Communication
PLATFORM_WEBHOOK_URL=https://lnchr.io/api/bot/webhook
BOT_WEBHOOK_SECRET=random-webhook-secret

# Fee Collection
PLATFORM_FEE_WALLET=0xYourFeeWalletAddress...
PLATFORM_FEE_PERCENT=1.0

Trading Bot (Python)

See BOT_CONTAINER_SPEC.md in the repo root for the full contract the Python bot container must implement.

# Set by platform automatically
BOT_ID=bot-uuid
NETWORK=ethereum
TRADE_AMOUNT_ETH=0.01
HOLD_DURATION_MINUTES=6
MIN_MARKET_CAP=27000
MAX_MARKET_CAP=59000

# Wallet (encrypted)
ENCRYPTED_WALLET=encrypted-private-key
WALLET_SALT=base64-salt
WALLET_IV=base64-iv
WALLET_ENCRYPTION_SECRET=encryption-secret

# Platform Communication
PLATFORM_WEBHOOK_URL=https://lnchr.io/api/bot/webhook
BOT_WEBHOOK_SECRET=webhook-secret

# Fee Collection
PLATFORM_FEE_WALLET=0x...
PLATFORM_FEE_PERCENT=1.0

# Ethereum mainnet
ETH_RPC_URL=https://eth.llamarpc.com
UNISWAP_V2_ROUTER=0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D
WETH_ADDRESS=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2