Turn a goal into a draft plan

POST /api/allocate turns a plain-language goal and a dollar amount into a draft basket: a named allocation over real assets, each leg with a weight, a one-line reason, and a blended risk score.

POST /api/allocate · requires a Privy bearer token. Base URL, rate limits, and error shapes: conventions.

Nothing is signed and nothing is spent here. Vera reasons over the buyable universe and twelve months of real price history, filters her picks to assets with a live two-way route at the venues, and normalizes weights to sum to 100. A walk-forward backtest against SPY is attached when history allows. Sign the plan afterward with POST /api/commit-plan.

Parameters

JSON body.

Name	Type	Required	Default	Description
goal	string, 1–600 chars	yes	—	The goal in plain words, e.g. “grow my money steadily for five years”.
amountUsd	number, >0 and ≤1000000	yes	—	The dollar amount to allocate.
riskTolerance	"conservative" | "balanced" | "aggressive"	no	inferred from goal	An explicit risk preference.

Returns

Field	Type	Description
summary	string	Short plain-language headline for the plan.
rationale	string	Two to four sentences explaining the plan.
riskScore	integer, 0–10000	Blended portfolio risk in basis points (broad ETFs ~3000–4500, single tech stocks ~5000–7000).
allocations	array	The basket. Each leg is { symbol, weightPct, reason }. Weights sum to 100.
backtest	object | null	One-year monthly-rebalanced backtest versus SPY, or null when under half the weight has usable history. Shape: POST /api/backtest.
amountUsd	number	Echo of the requested amount.
model	string	The inference model id that produced the plan.

Request

curl -X POST https://monvera.best/api/allocate \
  -H "Authorization: Bearer $MONVERA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "grow my money steadily for five years",
    "amountUsd": 100,
    "riskTolerance": "balanced"
  }'

Example response

{
  "summary": "Steady Growth",
  "rationale": "A balanced mix built for a five-year horizon. Most of the money sits in broad market exposure and short Treasuries, with two large tech names for growth.",
  "riskScore": 4200,
  "allocations": [
    { "symbol": "SPY", "weightPct": 40, "reason": "Broad US market in one holding." },
    { "symbol": "SGOV", "weightPct": 30, "reason": "Short US Treasuries, the low-volatility anchor." },
    { "symbol": "AAPL", "weightPct": 15, "reason": "Profitable, cash-rich, steady demand." },
    { "symbol": "NVDA", "weightPct": 15, "reason": "Strong trend, sized small because it swings hard." }
  ],
  "backtest": {
    "period": "1Y",
    "rebalance": "monthly",
    "coveragePct": 100,
    "excluded": [],
    "portfolio": { "returnPct": 18.4, "volPct": 12.1, "maxDrawdownPct": 9.7, "sharpe": 1.32 },
    "benchmark": { "symbol": "SPY", "returnPct": 21.0, "volPct": 13.6, "maxDrawdownPct": 11.2, "sharpe": 1.28 }
  },
  "amountUsd": 100,
  "model": "venice-uncensored"
}

symbol values render in-app as real names: SPY as “S&P 500”, SGOV as “US Treasuries”.

Errors

Status	Body	When
400	{"error":"Invalid request body."}	Schema validation failed: missing goal or amountUsd, goal over 600 chars, amount not positive or above 1000000, bad riskTolerance.

A 500 from this route usually means the model returned no usable plan, or every pick lacked live liquidity; rephrasing the goal often clears it. A price-history outage never fails the request — it returns backtest: null and the plan still comes back.

A draft plan is an option with reasons and a risk read, not advice: is this investment advice. Backtests are history, not promises.