Idea baskets
# Idea baskets
Idea baskets are limited to enabled partners. Check users.listFeatures() for baskets before showing them. The read routes and Link an order to a basket step answer 403 baskets_disabled when it is off for the user. A session sees only its owner's baskets; another owner's basket id answers not found.
Read the user's baskets
GET /v1/users/{userId}/baskets—baskets.list({ limit?, cursor? }), newest first. PassnextCursorunchanged to read the next page; stop when it is null. Each basket carries itsunusedvenue money andunusedUnavailablevenues, so a list can total what is left on venues without reading every basket.GET /v1/users/{userId}/baskets/{basketId}—baskets.get(basketId), including positions, the idea's kill condition, the cash it keeps back (cashKeptUsdc), how many steps its one approval covers (steps), when the owner approved it (approvedAt), failed or skipped buying steps with each step'slabel, unused venue money, andperformance.
In chat, Fin reads the same lists and baskets with basket_read, from any of the user's conversations, so it can answer about, finish, link or delete a basket made in another chat. A draft can still be revised or bought only in the conversation that drafted it; elsewhere Fin drafts it again as a new basket.
Performance
The existing detail GET and POST /v1/users/{userId}/baskets/{basketId}/links responses carry a mandatory performance object on Basket. No performance route or SDK method is added. baskets.list and BasketSummary are unchanged and do not carry performance; read the detail when drawing it.
import type {
BasketPerformance,
BasketPerformancePoint,
BasketPerformancePosition,
} from "@nearai/financial-agents-sdk";
const basket = await client.user(userId).baskets.get(basketId);
const performance: BasketPerformance = basket.performance;This illustrative JSON shows the complete performance shape, for a draft allocated entirely to one spot position. These example figures are not market data:
{
"mode": "estimate",
"asOf": "2026-11-16T12:00:00.000Z",
"startAt": "2026-11-09T12:00:00.000Z",
"endAt": "2026-11-16T12:00:00.000Z",
"chartPeriod": "7d",
"returnPctDecimal": "4.2",
"points": [
{ "at": "2026-11-09T12:00:00.000Z", "returnPctDecimal": "0" },
{ "at": "2026-11-10T12:00:00.000Z", "returnPctDecimal": "0.5" },
{ "at": "2026-11-11T12:00:00.000Z", "returnPctDecimal": "-0.8" },
{ "at": "2026-11-12T12:00:00.000Z", "returnPctDecimal": "1.4" },
{ "at": "2026-11-13T12:00:00.000Z", "returnPctDecimal": "0.9" },
{ "at": "2026-11-14T12:00:00.000Z", "returnPctDecimal": "2.7" },
{ "at": "2026-11-15T12:00:00.000Z", "returnPctDecimal": "3.3" },
{ "at": "2026-11-16T12:00:00.000Z", "returnPctDecimal": "4.2" }
],
"positions": [
{
"index": 0,
"returnPctDecimal": "4.2",
"leverageDecimal": null,
"source": "stored_token_closes"
}
],
"fundingIncluded": false,
"feesIncluded": false
}All fields shown are required. mode is "estimate" or "actual"; chartPeriod is "7d" or "since_bought". asOf is the observation time; startAt and endAt bound the reported period; an empty points array does not imply a measured curve exists. All timestamps, including point at, are ISO datetimes. positions[].index is the integer position index. The top-level and per-position returnPctDecimal may be null; point returns are always signed decimal strings. leverageDecimal is a decimal string for a perpetual's actual approved leverage, or null when not applicable. fundingIncluded and feesIncluded are required booleans: both false for draft estimates and both true for actual returns based on existing valuation.
Returns use percent units: "4.2" means +4.2%, "-1.8" means −1.8%, and "0" means unchanged, not missing. Keep these values as decimal strings and use exact decimal arithmetic, not Number or parseFloat. The server computes the returns and points; do not manufacture performance in the browser.
| Position / mode | positions[].source | Valuation evidence |
|---|---|---|
| Draft NEAR Intents spot assets | "stored_token_closes" | Stored token closing prices |
| Draft Hyperliquid perpetuals | "hyperliquid_candles" | Hyperliquid candles |
| Draft Polymarket outcomes | "polymarket_clob" | The selected outcome's CLOB price history |
| Bought holdings | "basket_valuation" | The basket's existing since-bought holding valuation |
Drafts: if bought a week ago
mode: "estimate" is a hypothetical seven-day return on the planned allocations, not a return the user earned. For each position the server computes (priceAtTime / startPrice - 1) × 100, reverses the sign for a short, and applies the perpetual's stored approved leverage. The basket return is the sum of each position return multiplied by its planned weightBps / 10000. Retained cash contributes zero; weights are not renormalized to remove cash. The current draft planner supports 1x perpetuals: do not copy a mockup's 2x label or invent leverage that the approved plan does not contain.
The chart has eight daily points, including the start seven days ago and now, with chartPeriod: "7d". Label it “Last 7 days” and “estimate, if bought a week ago”. Draft estimates exclude trading fees and funding; show those limitations, not a net-return claim.
If any position lacks the full seven days of history, its return is null, the basket return is null, and points is empty. Keep every position, including the missing one: never drop it or recompute a flattering return from only the covered subset. Hide the aggregate performance band and chart, and label unavailable position returns “new”, not 0%. Show all positions (up to 12), including a Polymarket outcome's market name.
Bought baskets: actual since bought
mode: "actual" reports the basket's existing since-bought valuation return, changeUsdc / costUsdc × 100, rather than replaying the proposed allocation. For each holding with priceSource: "market", its return is holding.changeUsdc / holding.costUsdc × 100; an unavailable or cost-only holding has a null return, rendered “—” rather than a draft's “new” chip. Actual positions use source: "basket_valuation", not one of the draft historical-price providers. If any holding lacks a market-valued return, the aggregate return is null too: suppress the total and explain that not every position has a live price. Do not substitute cost for a market observation or drop that holding. When every holding is market-valued, the headline uses the basket's existing return exactly, not an average of the holding percentages.
Actual returns inherit recorded settlement costs and attributed funding: feesIncluded and fundingIncluded are true. This does not mean every future fee or funding payment is known; do not present it as a guaranteed final net return. The valuation and shared-holdings limitations below still apply.
Actual chartPeriod is always "since_bought"; startAt is boughtAt, and endAt and asOf are the current valuation read time. Actual points is always empty: show an available return as a number only, with no chart. The response does not include per-basket historical valuation observations. No historical funding or cost curve is reconstructed from today's holdings, and no seven-day price-provider reads are made for actual returns. Do not infer observations from the period metadata.
Honor nulls and empty points for bought baskets too; never substitute an estimate or a fabricated line. A share's Amounts-off setting hides dollar amounts, not return percentages or the performance disclosures.
Delete a basket
DELETE /v1/users/{userId}/baskets/{basketId} — baskets.delete(basketId) removes a draft or a bought basket from the user's ideas and answers 204; the lists and reads then answer as if it never existed (another delete answers 404). It moves nothing: what the basket bought stays in the user's accounts, and unused venue money stays on the venue to withdraw, so say so before the user confirms. It is refused with 409 basket_buying while the basket is buying and 409 basket_awaiting_approval while an approval to buy it is still open; decline that approval first. A deleted draft cannot be revised or bought. Delete is not gated by the baskets feature, so a user can always remove their own basket. In chat, Fin does the same with basket_delete, at once and without an approval card.
Drafting and buying happen in chat. Buying asks for one approval of the exact venue trades, not permission to trade an idea indefinitely. Use the existing approval issuance and signing flow; sign the message Fin returns. A partial purchase does not roll back trades that succeeded. Offer the indicated withdrawal tool for unused venue money through chat, with a new approval; a read never withdraws anything.
A draft is a plan: its budget can be more than the agent wallet holds. The draft's walletShortfallUsdc says how much more USDC the wallet needed when it was drafted, so the user has a target; it is absent when the wallet held enough. Buying reads the wallet again and refuses, before any approval, with the exact amount still missing.
A step can itself fill only some trades. Such a basket is partly_bought, even if no whole step completed; inspect its positions and individual step results before proposing another purchase.
Finish a partly bought basket
A partly bought basket is never bought again as a whole. In chat, when the user asks to finish it, Fin proposes (basket_finish) the Hyperliquid and Polymarket orders that did not buy, at today's prices for the amounts the user approved, paid from money already on those venues: nothing more comes from the wallet, and a funding or spot step is not bought again. The proposal is a basket of its own with the ordinary draft card; buying it is one more approval of exactly those orders, whose signed contract's walletDebit is empty. Each order that buys then stands in for its step in the original basket (linked: "finished" on its holding), and the finishing purchase does not appear in the ideas list. If the venue money does not cover the orders, the proposal is refused; the user can move more there or link orders of their own.
Link an order to a step that did not buy
When the user buys what a failed step would have bought with an order of their own (in chat, each with its own approval, or on a venue page), link that order to the step so the basket shows and values it in the step's place:
- Each entry of
failureslistslinkableorders: orders the user placed since the basket's result, for the step's market or outcome and side (for perps also its leverage and margin mode), that received something and that no basket step holds yet. Show them with the step, and an empty list as nothing to link yet. A funding step never offers one. POST /v1/users/{userId}/baskets/{basketId}/links—baskets.link(basketId, { piece, operationId })links one of them and answers the basket. The step leavesfailures; its holding getslinked: "linked", its quantity and cost from that order's own fill, and a value like any other holding. When every step that did not buy is linked, the basket isbought.- It moves nothing and needs no approval. A link is permanent: repeating the same link answers the basket again; another order for a linked step is refused with
409 basket_step_linked, a step that bought (or a basket that is not partly bought) with409 basket_step_not_failed, and an order the step does not offer with400 basket_order_not_linkable.
In chat, Fin does the same with basket_link when the user asks to update the basket with orders they placed.
The 40% concentration limit counts each instrument across all actions and buying steps; splitting a purchase into several steps does not raise that limit.
Values are estimates
Quantities come from each buying step's recorded settlement, not the proposed allocation or the account's current balance. Cost is what that step paid in USDC. Intents assets use the wallet's current prices. Perpetuals (side long or short, both 1x isolated) use the current mark and funding: the position's since-open funding is attributed by size to the basket's fill, and a short is worth its margin plus the fall in price since entry. A position on the other side of the same coin is not the basket's, so its value reads null. This attribution is an estimate, especially after other trades change the same position. Polymarket positions are shown at cost (priceSource: "cost") until their price source has been reviewed.
Values and changes are exact decimal strings in USDC, truncated toward zero to six decimal places at the response boundary. A null value means unavailable, not zero. Totals include only unused venue money attributable to this basket's recorded funding, after its order costs, fees and reservations, capped by the current spendable venue balance. Pre-existing cash and money from other baskets are not counted.
If unusedUnavailable names a venue, its balance or attributable unused amount could not be established: do not show that as zero or imply no money was left there. Offer to review that venue account and withdraw through chat. A retained unused amount can be an estimate while the venue is unavailable; the overall value remains null until the missing amount can be priced. Hyperliquid unified accounts use their spendable spot USDC, not the perps-only withdrawable field.
Shared holdings
Assets, perpetual positions and outcome tokens are fungible across the owner's account. This page values what the basket bought, even if the user later buys or sells the same asset elsewhere. Show a shared-holdings disclaimer and the alsoHeldOutside note when the account's holding differs from the basket's quantity. The basket record is not a separately held or reserved portfolio.