Automated dollar-cost averaging (DCA) for FurlPay — "buy $10 of VOO every Monday with USDC." Schedule recurring, stablecoin-funded stock/ETF/crypto buys; a runner decides what's due and places the orders.

You own the schedules — create them here or seed from your own database.
Deterministic scheduling — pure, UTC-based due logic with catch-up (a slot fires once even if the runner was down, and never double-fires).
Clone-and-run — with no API key, orders are simulated so you can watch the DCA loop end-to-end. Zero runtime dependencies (global fetch, Node 18+).

Maintained by FurlPay · MIT licensed.

Install

npm i @furlpay/auto-invest

Usage

import { AutoInvest } from "@furlpay/auto-invest";

const ai = new AutoInvest({ apiKey: process.env.FURLPAY_API_KEY });   // omit key → simulate

ai.add({ symbol: "VOO", amount: 10, frequency: "weekly", dayOfWeek: 1 });   // Mondays
ai.add({ symbol: "BTC", amount: 25, frequency: "monthly", dayOfMonth: 1 }); // 1st of month
ai.add({ symbol: "AAPL", amount: 5, frequency: "daily" });                  // every day

// Run this on a cron (e.g. hourly). It buys everything currently due.
const results = await ai.runDue();
// [{ scheduleId, symbol, amount, currency, status, orderId?, simulated?, ranAt }]

Each due schedule places a fractional market buy for its notional via POST /investing/orders, funded in the schedule's currency (default USDC), and records lastRun so it advances to the next slot.

Scheduling

Frequency	Fires on	Options (UTC)
`daily`	every day at `hour`	`hour` (0–23, default 14)
`weekly`	`dayOfWeek` at `hour`	`dayOfWeek` (0=Sun…6=Sat, default 1), `hour`
`monthly`	`dayOfMonth` at `hour`	`dayOfMonth` (1–28, default 1), `hour`

The pure helpers are exported if you want to compute times yourself:

import { isDue, nextRun } from "@furlpay/auto-invest";
nextRun(schedule, new Date());   // next UTC fire time
isDue(schedule, new Date());     // should it run now?

API

Method	Purpose
`ai.add(input)`	Create a schedule (validates amount/day ranges) → `Schedule`
`ai.list()` / `ai.get(id)`	Read schedules
`ai.pause(id)` / `ai.resume(id)` / `ai.remove(id)`	Toggle / delete
`ai.nextRunAt(id)`	Next UTC fire time for a schedule
`ai.due(now?)`	Schedules due at `now`
`ai.runDue(now?)`	Buy everything due; records `lastRun` → `OrderResult[]`
`ai.runNow(id, now?)`	Force one schedule to buy now (ignores due check)
`ai.live`	`true` when an API key is set (else orders simulate)

Seed from your store and persist after each tick:

const ai = new AutoInvest({ apiKey, schedules: await db.loadSchedules() });
await ai.runDue();
await db.saveSchedules(ai.list());   // persists updated lastRun

Example

npm run example
FURLPAY_API_KEY=fp_live_sk_... npm run example

Test

npm test        # tsc build + node --test (demo mode, no network)

The suite pins the scheduling math (daily/weekly/monthly nextRun, isDue catch-up and no-double-fire), input validation, simulated runs recording lastRun, and the live path (correct POST body to /investing/orders, plus failed orders captured rather than thrown).

Scope

This library orchestrates FurlPay's investing API — it doesn't custody funds or execute trades itself; brokerage (via Alpaca) and settlement happen in the FurlPay API. Point it at your own FurlPay account and it invests on your behalf.