Conventions, limits, and errors

The base URL is https://monvera.best. Every request and response body is JSON. Every route enforces a fixed 60-second rate-limit window — public routes counted per client IP, gated routes per user id. Every error is one shape, {"error":"<message>"}, with the meaning carried by the status code. This page is the canonical version of all four; the route pages link here instead of repeating them.

Requests and responses

Send Content-Type: application/json on any route with a body and read application/json back. POST arguments are JSON fields, for example {"goal":"...","amountUsdg":"250"} on /api/allocate.

Value	Shape
USDG amounts	Strings of 6-decimal units — USDG has 6 decimals
Stock and ETF amounts	18-decimal ERC-20 units on chain 4663
Addresses	0x-prefixed hex, checksummed on the way out, case-insensitive on the way in
planId	bytes32 hex string
Timestamps	Unix seconds
Errors	{"error":"<message>"} plus a status code

Match on the status code, not the message text — some routes pass a more specific 400 message inside the same shape. Error messages never expose internals.

Danger

No route returns a private key, a seed phrase, or a session-signer secret in any field. Accounts are non-custodial and signing happens client-side through Privy. If an example shows a key in a response, it is fabricated.

Error codes

Status	Body	Triggered by
400	{"error":"Invalid request."}	A malformed or missing field. Some routes return a more specific message in the same shape.
401	{"error":"Please sign in to continue."}	A gated route with no bearer token, or a bad or expired Privy token.
429	{"error":"Too many requests. Please slow down a moment."}	The route’s 60-second window is exceeded. Carries a Retry-After header in seconds.
500	{"error":"Something went wrong. Please try again."}	An unexpected server error. Retry; if it persists, say so on X at @monvera_best.

On 429, read Retry-After and wait that many seconds. /api/autopilot/run also holds an in-flight lock and returns 429 with Retry-After: 30 when a run is already executing, even under the request limit. On 400, fix the body and resend — /api/alerts POST returns 400 once an account already holds 20 or more active alerts, independent of the rate limit.

There is no geo-gating: Monvera is available worldwide, and no route returns a region-based 451. (The former US/CA/UK/CH gate was removed in July 2026.)

Rate limits, public routes (per IP)

Route	Limit per 60s
/api/prices	60
/api/market	60
/api/screener	60
/api/vera-record	30
/api/portfolio	240
/api/transactions	120
/api/activity	120
/api/strategies	30
/api/backtest	20

Rate limits, gated routes (per user id)

Route	Limit per 60s
/api/pimlico	600
/api/watchlist (POST)	60
/api/quote	30
/api/commit-plan	20
/api/autopilot (POST)	20
/api/alerts (POST)	20
/api/allocate	12
/api/autopilot/run	6

On-chain reverts

commit-plan can accept your request and still revert on-chain. The revert rolls the whole transaction back, so a failed commit spends nothing. In order: PlanAlreadyRecorded(planId) if that planId was already committed, InferenceExpired() if the block timestamp is past expiry, RiskCeilingBreached(assessed, maxRisk) if assessedRisk exceeds maxRisk, and BadSigner(recovered) if the recovered signer is not the current agentSigner().

An expired inference is the common one, and a stale quote is usually the cause. Allocate and commit close together, and quote each leg as you execute it.

The worked example

Request examples across these pages use one story, so field values line up between routes: a plan named “Steady Growth” over Apple (AAPL), Nvidia (NVDA), the S&P 500 (SPY), and US Treasuries (SGOV), funded in USDG on chain 4663.

Symbol	Token address (chain 4663)
AAPL	0xaF3D76f1834A1d425780943C99Ea8A608f8a93f9
NVDA	0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC
SPY	0x117cc2133c37B721F49dE2A7a74833232B3B4C0C
SGOV	0x92FD66527192E3e61d4DDd13322Aa222DE86F9B5

GET /api/market is the source of truth for all 95 addresses — take them from the catalog, not from this table, if you are building against it.