Earning & personal Bundles

Status: canonical product direction and release requirements, September 5, 2026. This specification supersedes merchant-discovery-first positioning. Financial features remain planned until the corresponding implementation and provider gates pass.

The unified thesis and Clubs and Harvest extension add social discovery, optional managed strategies and customer-directed proceeds routing. They preserve this self-directed Bundle lifecycle and first financial release. Managed authority, compensation and collateral have separate approval gates.

1. Primary takeaway

Earn money. Build and trade your own asset bundles.

Forage exists to help customers earn real economic value and control the investments they create. Funded cash rewards, eligible income and dividends are earning sources. Buying, holding and selling selected assets creates investment results that may be positive or negative. Forage makes each source and the customer's net result understandable.

The primary product is the customer's earning and investing experience. Merchant offers, discounts, trails, referrals and collections help bring in value and repeat use. They do not replace live asset ownership and trading.

Public supporting copy:

Earn cash rewards and eligible income. Put your money into asset bundles you create, hold them in your own accounts, and buy, sell or rebalance when you choose. Investment values and income can change; returns are not guaranteed.

2. Bundle is a first-class product object

Bundle is the customer name for the existing Personal Basket model. It is a customer-created selection of eligible instruments, target weights or quantities, and a named account purpose. Each funded bundle has inspectable holdings, cash, income, cost basis, orders and performance.

The customer can create multiple bundles for different purposes and identify which subaccount holds each one. A draft is visibly unfunded. A funded bundle shows actual holdings even when they differ from its current target plan.

The intended custody model is an isolated customer-owned BASKET Account Instance where supported. A provider-bound implementation uses the provider's approved dedicated account and wallet. If a provider cannot support the requested isolation, Forage must disclose whether a bundle is only a labeled allocation within that customer's provider account or leave creation unavailable. A label cannot be represented as an independently controlled onchain subaccount.

A same-customer accounting allocation must assign every unit/lot only once and reserve it against all concurrent orders. It cannot create spendable duplicates or imply independent signing, custody or protection from sibling actions. Provider books remain authoritative. This fallback needs its own acceptance before release.

Trading a bundle means coordinating purchases or sales of its underlying holdings. This preserves the accepted AGW/subaccount model. It does not transfer the account's owner, issue a pooled share, create an ERC-6551 wrapper or list the account itself for sale. Sharing a bundle definition shares a non-executable plan, not ownership of the live assets.

A managed Club allocation is separately labeled and binds to the customer's isolated STRATEGY account. A vetted operator may choose executions within a separately signed instrument universe and limits under the approved operating structure. Joining a Club, importing a plan or reading an update never grants that discretion. The operator cannot access self-directed sibling Bundles; mandate expansion needs fresh consent.

3. Required customer actions

Action	Customer intent	Required result
Create bundle	Name it, select eligible assets and set weights/quantities	Save a versioned draft; no financial action merely from editing
Buy bundle	Allocate available customer funds across the selected plan	Review exact constituent orders, fees, minimums and settlement; authorize execution
Hold	Keep assets within the bundle's actual subaccount/provider account	Inspect source holdings, income and actual allocation without recurring activity requirements
Add money	Buy more using the current accepted plan	Show whether allocation follows targets or adds proportionally; disclose any new cash remainder
Sell part	Sell a stated percentage or chosen quantities	Show each proposed sale and estimated net proceeds; retain the remainder in the same account
Sell all	Sell all eligible tradable holdings	Disclose blocked positions, residual units and settlement; do not promise immediate full cash exit
Rebalance	Trade current holdings toward edited targets	Produce explicit buy/sell differences and cost/tax-lot implications before confirmation
Edit targets	Change the future allocation plan	New draft version only; current holdings remain unchanged until a separately confirmed trade
Use earnings	Select available income/rewards and a destination	Follow the approved funding path, then a reviewed bundle purchase or separately approved mandate
Withdraw proceeds	Move settled eligible cash to the customer	Explicit owner/provider-mediated withdrawal, independent of account-transfer or game mechanics

Buy, add, sell and rebalance are user-controlled core features. They do not wait for an AI strategy or unattended execution. AI may explain the allocation or prepare the customer's requested draft; it cannot select a new asset or sign outside existing authority.

4. Simple product surfaces

Keep Home, Explore, Portfolio. Home leads with the customer's economic result and earning sources. Portfolio prominently exposes My bundles, holdings and buy/sell actions, with managed allocations separately labeled. Explore contains earning opportunities, reviewed shared plans and Clubs; no social action grants financial authority. Harvest is a contextual action for eligible available funds, not another account or earning source.

The primary portfolio action is Create bundle for an empty portfolio. A funded bundle shows Add, Sell and Rebalance, with current value, allocation and income beside them. Cash funding, rights, price, cost and account ownership remain understandable without exposing a chain selector or session-key form.

Example journey:

Create "My long-term bundle"
  -> choose eligible instruments and weights
  -> choose $100 of available customer funds
  -> review account, holdings, fees and execution behavior
  -> confirm the required provider/wallet authorization
  -> track actual fills and settlement
  -> hold, add, sell a portion or rebalance from the bundle screen

Weights refer to selected eligible products, not an assumption that every token sharing a stock ticker grants the same rights. One bundle view may span multiple approved instances later, with each leg's actual location and restrictions preserved.

5. Make money outcomes accurate and visible

Home and each bundle distinguish:

Cash rewards earned: funded customer entitlements, net of applied adjustments and reward fees; pending claims are separate.
Income received: actual credited interest/fund income and dividends, with provider, period and applicable deductions.
Income accruing: separately labeled estimates or provider entitlements not yet available.
Realized investment result: sale proceeds less disposed-lot cost basis and attributable trading costs, with the method stated.
Unrealized investment result: current remaining holding value less its adjusted cost basis, with price source and timestamp.
Fees and net result: fees already included in another figure are not subtracted twice. Display known withheld tax separately; do not claim after-tax profit without sufficient data.

Customer deposits, internal transfers and gross sale proceeds are not earnings. Discounts show money saved at checkout; they are not cash received. A reward contributed into a bundle is a funding inflow, not investment performance. It is counted once as a reward at the customer level and excluded from the bundle's investment return calculation. Reinvested income updates basis and units without producing a second income event.

If Forage shows a combined economic-result summary, it must reconcile its source components over the same period, valuation currency and scope. Cash income/rewards and realized/unrealized investment P&L must remain inspectable. A negative overall result remains prominent even if cashback was positive. Neither a balance increase from a deposit nor the sale of principal may be called "money made".

The customer can inspect daily income observations without requiring a daily claim or visit. Rewards and yield do not guarantee positive trading returns, and the product must never suggest that more trades inherently create more money.

Missing cost basis or stale valuation makes the affected performance figure Unavailable or clearly estimated, not zero. Imported assets and corporate actions require basis provenance. Cash income generated within a fund's NAV is not added to investment performance again. Customer-wide reward benefit and bundle-level investment performance use explicitly different scopes.

6. Account and execution model

Minimum domain records:

Bundle: stable bundleId, owner Legal Account, Portfolio, name and lifecycle;
BundlePlanVersion: existing BasketSpec reference, instrument identities, weights/quantities, customer acceptance and version hash;
BundleAccountBinding: explicit Canonical Account, Account Instance/provider account and custody/isolation mode;
BundlePositionAllocation: authoritative source lot/unit references and allocation version when accounting partitions are used;
BundleOrderIntent: action, selected plan, input amount or sale quantities, total limits, execution policy and customer authorization;
BundleOrderLeg: account/instance, instrument, side, quantities, quote, provider order, status, fills and reserved funds/units;
BundleResult: actual composition, residual cash, received income, realized/unrealized result and reconciliation status.

bundleId is a product identifier; existing accountId, instanceId and basketSpecId retain their distinct meanings. Updating a BundlePlanVersion never changes live mandate permissions. A new asset, larger budget or expanded authority requires fresh customer authorization. AGW remains root control where approved; local delegates and mirrors retain independent limits and revocation.

An atomic onchain bundle trade is allowed only when every approved leg executes in the same enforceable transaction and the provider instruments support it. A sequence of broker orders or actions on different chains is not atomic. For those routes, disclose partial completion behavior before confirmation and track a parent intent plus each child order independently.

The parent intent distinguishes DRAFT, REVIEW_READY, AUTHORIZED, SUBMITTING, WORKING, PARTIALLY_FILLED, SETTLING, COMPLETED, PARTIAL_COMPLETED, CANCELLED, FAILED, and NEEDS_REVIEW. COMPLETED means all intended actions met the accepted completion rule and reconciled; a partial fill cannot silently become success.

Each leg reserves funds/units once and retains an idempotency key. A timeout does not permit a duplicate order. A cancellation request does not erase completed fills or release ambiguous commitments. Do not automatically reverse successful trades to "undo" a partial basket; that would be another price/tax-sensitive financial action. Apply only a recovery policy the customer explicitly approved, or prepare a new review.

For a weight-based plan, weights including any cash allocation total 100%; quantities and fee reserves must fit the reviewed spend limit. Use exact units and deterministic rounding. All expected fees, minimum order sizes and unallocated cash are part of the preview. Live ownership and order reservations, not target weights, determine what is available to sell.

Sell-funded buy legs proceed only when the provider makes proceeds available under the accepted funding policy. Do not assume leverage, cross-account funding or instant availability. Actual cash residuals, fractional minimums and blocked positions remain visible.

7. Release acceptance

The first full Forage release must let an eligible customer:

See real funded rewards or supported income, with pending and earned amounts distinct.
Create a bundle of multiple eligible assets and identify the account holding it.
Buy the selected bundle and reconcile actual holdings to the provider/chain.
Hold it and inspect cash income, actual allocation, cost and private performance.
Add funds, sell part, sell all eligible holdings and explicitly rebalance.
Understand partial fills, blocked legs, cash residuals and total fees.
Withdraw eligible settled proceeds using the approved owner/provider path.
Keep sibling bundles isolated according to the disclosed custody mode.

A merchant-only pilot remains useful but does not satisfy this definition. Customer-mediated bundle trading is part of the core financial release; background automation and broader mirrors follow later. Provider support for multileg orders, account isolation, wallet validation, market data and cost basis must be proven for the selected launch route.

8. References and precedence

Account and mirror specification — canonical identities, ownership and instance boundaries.
End-user experience — simplicity, review and recovery.
Rewards and income architecture — funding and attribution.
Personal Basket research — original basket design and invariant analysis.
Dinari order flow — provider order requests, fills and fulfillment; does not establish an atomic multileg order.
Dinari U.S. requirements — dedicated account/wallet, eligibility and transfer restrictions; provider approval remains required.

This product priority controls over earlier wording that makes merchant discovery the main purpose or treats bundle creation/trading as optional expansion. Existing research dates and economic assumptions are unchanged.

References to supporting material outside this public library are shown as text, not broken links.