Portfolio context

The holdings, trades, and profile model every Clarity call runs against.

Every Clarity call (card, chat, or iframe) runs against a portfolio context: current holdings, optional closed positions, an optional trade log, and an optional investor profile. This page documents that model. For the endpoints and SDK methods that operate on it, see Integrate Clarity and the API reference.

---

Inline vs persisted

Mode	When to use
Inline (pass a portfolio payload with each call)	Stateless integrations, one-off queries, prototyping
Persisted (create a partner portfolio once, reference it by id)	Production integrations, the iframe embed, recurring updates

Persisted portfolios are isolated from any other Motif data and scoped to your organization. They're the recommended pattern for production: lower bandwidth, a single source of truth, and required by the iframe embed when binding a token to a specific portfolio.

---

Holdings

The shape used in currentHoldings and the inline payload:

interface PartnerHoldingInput {
  ticker: string                     // e.g. "AAPL", "BTC", "VWRL.SW"
  quantity: number | string          // accepts numeric strings for precision
  costBasis?: number | string | null // per-unit average buy price
  currency?: string | null           // ISO 4217 or symbol, e.g. "USD"
  asOf?: string | null               // ISO timestamp; defaults to now
}

ticker is the most important field. Clarity uses it to resolve fundamentals, news, and research. Use the most canonical exchange-listed symbol for the best retrieval quality.

---

Historic holdings

historicHoldings is optional and carries closed positions so Clarity can reference them in commentary ("you sold X right before Y", "your realised gains on Z were…").

interface PartnerHistoricHoldingInput {
  ticker: string
  quantity: number | string
  openedAt?: string | null
  closedAt?: string | null
  realisedPnl?: number | string | null
  currency?: string | null
}

---

Trades

trades is an append-only log of executions:

interface PartnerTradeInput {
  ticker: string
  side: 'BUY' | 'SELL'
  quantity: number | string
  price: number | string
  executedAt: string                 // ISO timestamp, required
  currency?: string | null
}

Motif retains at most the 5000 most recent trades by executedAt. Older entries are dropped. For steady-state updates, prefer recordTrades (or POST /v1/sdk/partner-portfolios/{id}/trades) over a full update. It appends, caps the log, and replaces currentHoldings in one atomic call.

---

Investor profile

profile is optional. Clarity tailors tone and risk framing from it:

interface PartnerProfileInput {
  riskTolerance?: string             // "conservative" | "moderate" | "aggressive"
  horizonYears?: number | null
  goals?: string[] | null            // e.g. ["retirement", "house"]
  baseCurrency?: string | null       // ISO 4217
  annualIncome?: number | string | null
  netWorth?: number | string | null
  notes?: string | null              // free-text context for Clarity
}

notes is unstructured. Use it for context like "client prefers dividend strategies" or "active trader, weekly cadence".

---

External ID

Persisted portfolios carry your own externalId. It's required and must be unique within your organization. Clarity echoes it back on every card response so you can correlate logs and audit trails:

{ externalId: "acme-user-42-portfolio-main" }

---

Conventions and limits

• Tickers: any string up to 32 characters. Resolve to canonical exchange symbols when possible.

• Quantity / price / cost basis: number or numeric string. Use strings to preserve precision beyond IEEE-754.

• Currency: ISO 4217 codes (USD, EUR, CHF…) recommended. Crypto symbols (BTC, ETH…) are accepted.

• Trade log: capped at 5000. Provide a representative recent history rather than a full lifetime log.

• Portfolio count: one partner portfolio per end-user portfolio. Model multiple portfolios per user as distinct records with distinct externalIds.