Portfolio

Portfolio reads require a personal access token with portfolio:read. These docs cover the AGARA exchange; keep the returned exchange fields in your models so each row remains self-identifying.

Summary

GET /trade/v1/portfolio/summary

Use the summary before sizing a new order and after any deposit, withdrawal, position operation, or automatic redemption.

curl "$AGARA_BASE_URL/trade/v1/portfolio/summary?exchanges=AGARA" \
  -H "Authorization: Bearer $AGARA_API_TOKEN"

{
  "summaries": [
    {
      "exchange": "AGARA",
      "cash_balance_micro": "250000000",
      "free_cash_micro": "250000000",
      "positions_value_micro": "18500000",
      "portfolio_value_micro": "268500000",
      "open_cost_basis_micro": "17200000",
      "open_unrealized_pnl_micro": "1300000",
      "as_of": "2026-07-20T12:00:00.000Z"
    }
  ]
}

Resting BUY commitments are not a separate summary field. Read open orders and account for their remaining collateral when your strategy computes its own available quoting budget.

Positions

POST /trade/v1/portfolio/positions/list

Positions are returned as one complete snapshot, not a paginated list.

{
  "condition_ids": [],
  "exchanges": ["AGARA"]
}

An empty condition_ids array returns every current position. Use one or more condition IDs to narrow the snapshot.

{
  "positions": [
    {
      "exchange": "AGARA",
      "condition_id": "0x...",
      "token_id": "1234567890",
      "shares_micro": "5000000",
      "available_shares_micro": "3000000",
      "avg_price_micro": "430000",
      "current_price_micro": "470000",
      "current_value_micro": "2350000",
      "to_win_micro": "5000000",
      "profit_loss_micro": "200000",
      "profit_loss_percent": "9.302325581395348837",
      "redeemable": false,
      "mergeable": false,
      "mergeable_shares_micro": null
    }
  ],
  "markets": {
    "1234567890": {
      "market_id": "1f9e566d-7823-49fb-a5c5-5a193eba3209",
      "market_title": "Will City A win?",
      "outcome_name": "Yes",
      "logo_url": null,
      "event_slug": "city-a-vs-city-b",
      "display": { "market": {}, "outcome": {} }
    }
  },
  "events": {
    "city-a-vs-city-b": {
      "event_title": "City A vs City B",
      "display": { "event": {} }
    }
  },
  "unavailable_exchanges": [],
  "as_of": "2026-07-20T12:00:00.000Z"
}

shares_micro is your total holding. Use available_shares_micro as the maximum size for a new sell order — it excludes shares your own open sell orders have already committed, so "0" means every share you hold is already up for sale.

mergeable and mergeable_shares_micro are advisory snapshots for a held, available complete pair. redeemable identifies a resolved position; supported standalone markets are handled by automatic redemption. Retry when unavailable_exchanges contains AGARA because that snapshot is missing AGARA rows.

Open orders

POST /trade/v1/portfolio/open-orders/list

{
  "token_ids": [],
  "exchanges": ["AGARA"],
  "limit": 100
}

The response contains:

• orders: non-terminal order rows in the same shape documented under Orders;
• markets: metadata keyed by token_id, including raw market/outcome display objects;
• events: metadata keyed by event slug, including the raw event display;
• pagination: next_cursor and the applied limit;
• as_of: the snapshot time.

Orders are newest first. Pass pagination.next_cursor back as cursor with the same token_ids and exchanges filters. A null cursor means the walk is complete.

Trades

GET /trade/v1/portfolio/trades

Query parameters are limit (default and maximum 500) and an opaque cursor from the previous response.

{
  "trades": [
    {
      "exchange": "AGARA",
      "trade_id": "<uuid>",
      "fill_id": "42",
      "order_id": "<uuid>",
      "token_id": "1234567890",
      "side": "BUY",
      "shares_micro": "1000000",
      "price_micro": "470000",
      "fee_micro": "0",
      "role": "MAKER",
      "status": "CONFIRMED",
      "transaction_hash": "0x...",
      "executed_at": "2026-07-20T11:58:00.000Z"
    }
  ],
  "markets": {},
  "events": {},
  "pagination": { "next_cursor": null, "limit": 500 },
  "unavailable_exchanges": [],
  "as_of": "2026-07-20T12:00:00.000Z"
}

fill_id is serialized as a string. transaction_hash remains null until settlement supplies one. Keep paging until next_cursor is null; retry a page when unavailable_exchanges contains AGARA.

Activities

GET /trade/v1/portfolio/activities

Activities are a snapshot-stable AGARA history sorted newest first. limit defaults to 50 and accepts 1 through 500; pass the opaque cursor to continue the same walk.

The type discriminator selects one of these wire shapes:

ORDER appears only for a terminal order with at least one fill. fill_status is FULL or PARTIAL; status is MATCHED, CANCELLED, EXPIRED, REJECTED, or FAILED.

{
  "activities": [
    {
      "type": "REDEEM",
      "exchange": "AGARA",
      "id": "redeem:<uuid>",
      "condition_id": "0x...",
      "token_id": "1234567890",
      "shares_micro": "5000000",
      "amount_micro": "5000000",
      "tx_hash": "0x...",
      "created_at": "2026-07-20T11:55:00.000Z"
    }
  ],
  "markets": {},
  "conditions": {},
  "events": {},
  "pagination": { "next_cursor": null, "limit": 50 },
  "as_of": "2026-07-20T12:00:00.000Z"
}

The metadata sidecars cover only rows present on the current page: markets is keyed by outcome token ID, conditions by condition ID, and events by event slug. Activities do not return unavailable_exchanges.

Position operations

Split and merge convert between collateral and complete binary token pairs:

• POST /trade/v1/portfolio/positions/split requires positions:split;
• POST /trade/v1/portfolio/positions/merge requires positions:merge.

Both accept a scoped personal access token and return 201 with batch_hash, status: "PENDING", and as_of. Poll GET /trade/v1/batches/{batch_hash} for settlement. See Positions for request shapes, validation, merge-all, and cross-match settlement.

Supported resolved standalone markets use automatic redemption; no client-submitted operation is required.

Withdrawals

The standard withdrawal flow requires a current browser session. A personal access token alone cannot execute it.

• Same-chain withdrawal sends USDC to an address on Base.
• Accepted AGARA withdrawals return 201 with a pending batch hash. Poll the batch until it reaches SETTLED before treating destination funds as final.
• Requests queue per account and settle in order. A 409 means the queue is full or a merge-all is settling; retry once one finishes.
• The minimum is 10000 micro units. The environment's batch ceiling can impose a tighter bound.

For a cross-chain withdrawal:

1. Use a personal access token to read GET /trade/v1/portfolio/bridge/withdraw/supported-assets.
2. Request POST /trade/v1/portfolio/bridge/withdraw/quote with the destination chain, token, recipient, and source amount.
3. Review the current quote, then confirm in the signed-in web flow.

If a route refunds to the AGARA account, the return appears as a DEPOSIT activity. A quoted route minimum can be higher than the standard withdrawal minimum. Request a new quote before retrying.

Common pattern

Before placing a new quote, fetch summary and open orders together. Use the summary's free_cash_micro as AGARA's current BUY-validation cash, then apply your own risk limits and account for the remaining commitments in open orders.

Every portfolio endpoint's full request and response shape is in the Portfolio API reference.