Automate your holdings updates with your own agent

What the pipeline does

With active Jade, your own agent can turn an institution's holdings export into an updated current book in Portfonia. It checks the source, reads your book, prepares and validates changes, writes them, and checks change history. Your agent and tooling handle institution access, exports and scheduling. Portfonia does not log in to institutions, download statements or schedule these runs; it stores and updates your holdings records and does not execute trades.

Set up once

On the AI Agent page, create a holdings-write token for an agent that updates holdings, or a read-only token for one that only reads. Give your agent the token and https://portfonia.com/llms.txt. It first calls GET /agent/v1/token (Verify token permissions). An updating agent stops if capabilities.holdings_write is false; a read-only agent stops if capabilities.holdings_read is false.

Each run, step by step

  1. Check that the source export covers every account at the institution and has the expected as-of date. Skip a partial or stale export.
  2. Read GET /agent/v1/holdings and keep the returned version and each holding's id.
  3. Match existing rows by stable holding ID, never by ticker alone. The same instrument in two accounts is two rows.
  4. Change only rows belonging to this institution. Use POST /agent/v1/holdings to create, PATCH /agent/v1/holdings/{holding_id} to update, or DELETE /agent/v1/holdings/{holding_id} to delete. A single DELETE removes the ID in the path. Alternatively, PUT /agent/v1/holdings must list every other row unchanged: retain existing rows in holdings and explicitly list deleted IDs in delete_ids. An existing row omitted from both lists makes the whole request fail.
  5. Before creation, whole replacement, single-row replacement or PATCH, call POST /agent/v1/holdings/validate with operation create, replace_all, replace or patch and the corresponding fields described in agent.md. Continue only if valid is true, then write using the current version. Single-row replacement uses PUT /agent/v1/holdings/{holding_id}. Deletion has no validation step; send its current version in the quoted If-Match header instead of a JSON body. Validation does not reserve a version or guarantee a later write.
  6. On 409 version_conflict, read the book again and recompute the intended change. Never resend an old body with only its version swapped. Use the returned version for each subsequent write.
  7. For POST creation, send an Idempotency-Key. After a timeout, retry with the same key and the same body, including the original version, within 24 hours to get the original result. Read again before another write.
  8. Afterwards, read GET /agent/v1/holdings/changes with inclusive ET start and end dates within the last 30 days to confirm what changed. If truncated is true, narrow the date range. Unchanged writes and idempotent replays create no change-history group.

Limits and safeguards

Jade allows 100 stored holding rows, counting cash and watched rows. Single-row writes share 30 requests per minute and 100 per hour across your tokens. Reads, whole PUT and validation use the normal read limits. Quiet windows pause requests from five minutes before a heavy scheduled task until five minutes after it ends; use Retry-After when a request is refused. The last holding cannot be deleted through the API; clear the entire book only on the web. Successful current-holdings, change-history, snapshot and Jade risk-result reads share at most one access notice per ET day. Successful writes may trigger a separate daily modification notice; validation and idempotent replay send no data notice. A notice link revokes every token on your account at once, including other agents' tokens. It stops future access and does not undo saved changes. An Agent write or file upload that sharply reduces holdings rows or changes total value may trigger a separate alert email, at most one per Eastern Time date of the write.

What changes in Portfonia

Writes update Portfonia's saved current book. Later briefings and the Jade tools—holdings replay, tail risk, historical stress scenarios, style exposure and tracking—use the updated book. Every request is audit-logged; the audit stores request metadata, not holding bodies or complete tokens.