Autopilot API

Autopilot invests a set amount on a schedule without you signing each run, but only ever inside four bounds you set. /api/autopilot holds the config, /api/autopilot/run fires one run now, /api/autopilot/runs is the audit trail.

GET/POST/DELETE /api/autopilot · POST /api/autopilot/run · GET /api/autopilot/runs — all require a Privy bearer token. Base URL, rate limits, and error shapes: conventions.

The four bounds are amountUsd, cadence, riskCeilingBps, and maxPerPeriodUsd (defined below); every run is checked against all four before anything is signed. walletId is your Privy embedded-wallet id — granting it lets Monvera’s server sign each run’s spend, and DELETE revokes it along with the config. Vera signs the RiskInference risk assessment; the delegated signer signs the spend.

Read, set, and revoke the config

GET returns your config or {"autopilot": null}. POST creates or updates it, resets the schedule, and returns the stored config plus cadenceSeconds (daily 86400, weekly 604800, biweekly 1209600, monthly 2592000); limited to 20 POSTs per 60 seconds. DELETE removes it and returns {"ok": true}.

curl -X POST https://monvera.best/api/autopilot \
  -H "Authorization: Bearer $MONVERA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "wlt_9f2c…",
    "owner": "0x1111111111111111111111111111111111111111",
    "smartAccount": "0x2222222222222222222222222222222222222222",
    "goal": "grow my money steadily for five years",
    "amountUsd": 25,
    "cadence": "weekly",
    "riskCeilingBps": 6000,
    "maxPerPeriodUsd": 50
  }'

Field	Type	POST	Description
walletId	string	required	Embedded-wallet id the server signs each run’s spend with. Must be yours.
owner	address	required	Embedded EOA that owns the smart account and holds the USDG.
smartAccount	address	required	Smart account that executes the sponsored transaction.
goal	string (1–600 chars)	required	Plain-language goal Vera re-allocates against each run.
amountUsd	number (> 0, ≤ 100000)	required	Bound 1: USD invested per run.
cadence	daily | weekly | biweekly | monthly	required	Bound 2: how often a run happens.
riskCeilingBps	integer (0–10000)	optional	Bound 3: assessed risk must stay at or under it. Defaults to 6000.
maxPerPeriodUsd	number (> 0, ≤ 1000000)	optional	Bound 4: spend cap per period; a run over it is skipped. Defaults to amountUsd * 2.

The stored config echoes those fields and adds server-managed ones: id (ap_<userId>), userId, active, runs, Unix seconds createdAt / nextRunAt / lastRunAt, and spentThisPeriod — USD deployed this period, which enforces maxPerPeriodUsd.

Status	Body	When
400	{"error":"Invalid autopilot settings."}	Bad cadence, non-positive amountUsd, malformed address, or goal over 600 chars.
400	{"error":"That wallet does not belong to your account."}	walletId or owner is not your own embedded wallet.

Trigger a run

POST /api/autopilot/run takes no body. It runs your saved config now and submits a real on-chain transaction, counting the spend against the current period rather than starting a new one.

Only one run per account can be in flight, and the route is tight-limited to 6 calls per 60 seconds. A run can take up to two minutes; do not retry on timeout, the in-flight lock will refuse it.

curl -X POST https://monvera.best/api/autopilot/run \
  -H "Authorization: Bearer $MONVERA_TOKEN"

Returns {"ok": true, "txHash": "0xabc…"} when the run settles on chain 4663, or {"ok": false, "reason": "…"} when it was skipped or failed. If the transaction reverts after signing, reason is Run reverted (tx 0x…) and carries the reverting hash.

Bound checks that return ok: false before anything is signed:

reason	Meaning
Not enough cash for this run.	USDG balance below amountUsd.
Period spend cap reached.	Would push spentThisPeriod past maxPerPeriodUsd.
Plan exceeds your risk ceiling.	Assessed risk above riskCeilingBps.
Autopilot is paused.	Config is not active.
Amount too small to split across the plan's holdings.	A leg falls below the minimum tradable size.

Status	Body	When
400	{"error":"No autopilot is configured."}	No config; POST one first.
429	{"error":"Too many requests. Please slow down a moment."}	Over 6 calls in 60 seconds, or a run is already in flight — that case returns Retry-After: 30.

List runs

GET /api/autopilot/runs returns your last 20 runs, newest first. The trail is append-only and records every run — settled, skipped, or errored — so you can reconcile what Autopilot did against what you authorized.

curl https://monvera.best/api/autopilot/runs \
  -H "Authorization: Bearer $MONVERA_TOKEN"

{
  "runs": [
    {
      "ranAt": 1751884800,
      "amountUsd": 25,
      "assessedRiskBps": 4200,
      "status": "success",
      "txHash": "0xabc123…",
      "holdings": [
        { "symbol": "AAPL", "weightPct": 30, "amountUsd": 7.5 },
        { "symbol": "SGOV", "weightPct": 15, "amountUsd": 3.75 }
      ]
    },
    { "ranAt": 1751280000, "amountUsd": 25, "status": "skipped", "reason": "Not enough cash for this run." }
  ]
}

Each record also carries userId. status is success, skipped, or error; txHash and holdings appear only on success. That txHash is the checkable end of the record: one transaction on chain 4663 that both bought the holdings and recorded Vera’s signed risk assessment. Open it on Blockscout.