# 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. Pass `nextCursor` unchanged to read the next page; stop when it is null. Each basket carries its `unused` venue money and `unusedUnavailable` venues, 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's `label`, unused venue money, and `performance`.

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.

```ts
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:

```json
{
  "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 `failures` lists `linkable` orders: 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 leaves `failures`; its holding gets `linked: "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 is `bought`.
- 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) with `409 basket_step_not_failed`, and an order the step does not offer with `400 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.
