Skip to content

API.md

Latest commit

 

History

History
162 lines (105 loc) · 3.5 KB

API.md

File metadata and controls

162 lines (105 loc) · 3.5 KB
Raw

API reference

Base URL: http://localhost:8787 (or API_PORT from .env).

All responses are JSON unless noted. Errors return { "error": "message" } with 4xx/5xx status.

Health

GET /api/health

{ "ok": true }

Status & config

GET /api/status

Full operator snapshot: wallet balances, active session, pool info, cycle stats, efficiency metrics.

Key fields:

Field Description
wallet.balanceEth Base wallet native balance
wallet.subWallets Aggregate ETH in active cycle wallets
operating.headroomEth Balance minus stop threshold
pool Resolved route (version, fee, liquidity)
stats.totals.volumeEth Session volume
stats.efficiency Spent vs volume ratios

GET /api/config

Default and last-session config from config.ts + sessionStore.

GET /api/preflight

Economics prediction for a token.

Query params:

Param Required Description
token No* Token address (0x…)
amountMin No Override min trade size
amountMax No Override max trade size
subWalletNum No Wallets per cycle
parallelWallets No Parallel slot count

*Uses active session token if omitted.

Example:

GET /api/preflight?token=0xabc...&amountMin=0.002&amountMax=0.005

Bot control

POST /api/bot/start

Start the bot process. Body (all optional — falls back to config defaults):

{
  "targetTokenAddress": "0x...",
  "amountMin": 0.002,
  "amountMax": 0.005,
  "subWalletNum": 20,
  "parallelWallets": 4,
  "endlessMode": true,
  "minBaseBalanceEth": 0.005,
  "tradeScheduleMode": "pipeline",
  "tradeSizeBias": "max"
}

POST /api/bot/stop

Stop managed bot process. Returns { "stopped": true } or error if not running.

Sessions

GET /api/sessions?limit=50

List recent sessions (newest first).

GET /api/sessions/:id

Session detail with cycle totals and timeseries points.

Wallets

GET /api/wallets/cycles

List wallet JSON filenames in wallets/.

GET /api/wallets?file=<name>&balances=1

Load a cycle file. balances=0 skips on-chain balance fetch.

Fund recovery

POST /api/gather

Sweep native ETH from sub-wallets to base.

{ "latestOnly": true }

latestOnly: false scans all cycle files (slower).

POST /api/liquidate

Sell stranded ERC-20 on sub-wallets, then sweep native ETH to base.

{
  "latestOnly": true,
  "tokenAddress": "0x..."
}

tokenAddress is optional — uses active session token if omitted.

Returns: sold, gathered, sellFailed, recoveredEth, tokenAddress, etc.

Logs

GET /api/logs?lines=300

Tail of bot log (max 800 lines). Returns { "log": "...", "path": "..." }.

GET /api/logs/stream

Server-Sent Events stream of log append chunks. Dashboard prefers polling /api/logs to avoid memory growth.

Stats

GET /api/stats/timeseries

Cumulative volume/cost points for session chart. Uses DB if session active, else parses log file.

CORS

API enables CORS for local dashboard dev (cors() middleware). Do not expose publicly without authentication.

Example: start bot via curl

curl -X POST http://localhost:8787/api/bot/start \
  -H "Content-Type: application/json" \
  -d '{
    "targetTokenAddress": "0xb66d83f0a7eae1bed80df1e049a5d6aefa90eb66",
    "amountMin": 0.002,
    "amountMax": 0.005,
    "subWalletNum": 20,
    "tradeScheduleMode": "pipeline",
    "tradeSizeBias": "max"
  }'