Portfolio projection#

GET /v1/portfolio is the canonical, cache-only read of the latest complete Polymarket + Hyperliquid Balance checkpoint. It executes the existing unified projection implementation and never calls a provider or node in the request path. A cold or hard-expired wallet returns balanceHead: null; it never fabricates $0 or publishes a partial total.

The same implementation exposes GET /v1/portfolio/performance, POST /v1/portfolio/performance/heads/batch, and POST /v1/portfolio/refresh. The public URL and response contract are both v1 (schemaVersion: 1). The underlying Balance/Performance projection remains the latest implementation; internal ledger, event, and persistence versions are not HTTP API versions. No /v2/portfolio* routes are published.

Deprecated synchronous portfolio#

GET /v1/portfolio/legacy preserves the old provider fan-out response while fund valuation and migration consumers move to dedicated positions, cash, and account-state APIs. Do not use it for Total Assets, NAV, or PnL.

When to use the legacy endpoint#

• Existing internal fund or migration code that still requires provider-native position/account-state payloads while it moves to a dedicated operational API.
• Do not add new consumers. The route requires an admin-scoped key and may synchronously query providers. It is not a Total Assets, NAV, or PnL source.

For per-wallet trade history (fills, fees, etc.) use /v1/me/fills — it shares the same wallet identity model.

Request#

bashcurl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/portfolio/legacy?user=0x9d84cbc7eb19c4cbb24f3866c70a5fcab502d1dc&provider=polymarket,hyperliquid"

Query parameters#

Polymarket and Hyperliquid often use different addresses for the same user (PM deposit-wallet vs HL native EOA). Pass pmUser / hlUser to query each with its own address in a single call; each slice echoes the address it resolved. If a per-provider override covers every requested provider, user is optional.

Unknown provider names return 400 unknown_provider with the offending values listed. The full set lives in the providers field of every response so you can discover-then-filter.

Response#

jsonc{
  "schemaVersion": 1,
  "complete": true,
  "user": "0x9d84cbc7eb19c4cbb24f3866c70a5fcab502d1dc",
  "providers": ["polymarket", "hyperliquid"],
  "slices": [
    {
      "provider": "polymarket",
      "address": "0x9d84cbc7eb19c4cbb24f3866c70a5fcab502d1dc",
      "native": [
        // Verbatim Polymarket position array — one row per market the
        // wallet has any size on. Keys match Polymarket's own API.
      ],
      "valueUsd": 1234.56,
      "availableUsd": 250.0,
      "navUsd": 1484.56,
      "note": null,
    },
    {
      "provider": "hyperliquid",
      "address": "0x9d84cbc7eb19c4cbb24f3866c70a5fcab502d1dc",
      "native": {
        // Verbatim HL `clearinghouseState` (main perp dex) — assetPositions[],
        // marginSummary, crossMarginSummary, withdrawable, time.
      },
      "valueUsd": 5678.9,
      "availableUsd": 1200.0,
      "navUsd": 5678.9,
      "source": "node",
      "asOf": "2026-08-06T15:54:43.808Z",
      "buckets": [
        { "kind": "perp", "usd": 78.9 },
        { "kind": "spot", "usd": 5400.0 },
        { "kind": "vault", "usd": 200.0 },
        { "kind": "staking", "usd": 0 },
      ],
      "accountMode": "unifiedAccount",
      "note": null,
    },
  ],
  "summary": {
    "totalNavUsd": 7163.46,
    "totalValueUsd": 6913.46,
    "totalAvailableUsd": 1450.0,
    "providersReporting": 2,
    "providersRequested": 2,
  },
  "warnings": [],
  "fetchedAt": "2026-05-19T07:00:00.000Z",
}

Aggregation semantics#

• slices[i].address is the 0x address actually queried for that provider. With pmUser / hlUser overrides PM and HL can resolve to different addresses; without them both echo user.
• slices[i].native is the untransformed upstream payload. Polymarket returns an array (one row per position); Hyperliquid returns an object (the full clearinghouseState envelope including assetPositions[], marginSummary, crossMarginSummary, withdrawable, and time). Consumers that want raw venue data don't have to make two more calls.
• slices[i].source / asOf (Hyperliquid) identify the authoritative upstream (node or official) and its validated L1 timestamp. native, availableUsd, valueUsd, and the bucket breakdown all come from this same acquisition; Artery never combines a raw state from one moment with a valuation from another. A stale node timestamp triggers official fallback.
• slices[i].valueUsd is the USDC-denominated wallet value when the provider exposes one, else null. Polymarket returns position notionals; Hyperliquid returns the complete account value — perp equity across every dex (main + HIP-3/builder) + spot holdings + vault deposits + staking — the same number /v1/me/stats reports. It is not just the main-dex marginSummary.accountValue shown in native: a wallet whose funds sit in spot or an xyz: builder dex has near-zero native equity but a real valueUsd.
• slices[i].availableUsd is idle/withdrawable cash NOT in open positions, USD. Hyperliquid = clearinghouseState.withdrawable; Polymarket = the deposit wallet's on-chain idle collateral (pUSD + USDC.e). null when the provider didn't expose it. Note (Hyperliquid): this is a subset of valueUsd (a liquidity breakdown), not additive — see navUsd.
• slices[i].navUsd is the clean, provider-consistent account NAV — the single number to use as "this provider's total assets" (identical to /v1/me/wallets/{id}/nav navUsdc). It resolves the valueUsd/availableUsd asymmetry:
  • Hyperliquid: navUsd = valueUsd — valueUsd is already the complete account value (cash included), so availableUsd is not added.
  • Polymarket: navUsd = valueUsd + availableUsd — positions plus idle cash (the two are disjoint). null only when the provider reported no value at all. Use navUsd (not valueUsd + availableUsd) for account totals — adding the two uniformly double-counts Hyperliquid.
• slices[i].buckets (Hyperliquid) breaks valueUsd down by sub-account: perp / spot / vault / staking. Use it to reconcile against the HL app — each bucket maps to an HL portfolio tab, and the sum equals valueUsd.
• slices[i].accountMode (Hyperliquid) echoes HL's userAbstraction mode. On unifiedAccount / portfolioMargin wallets the account is ONE pool on the spot clearinghouse (the spot USDC total is marked live, uPnL included), so valueUsd = Σ spot value + vault + staking — equal to HL's own account value. The perp bucket shows the per-dex accountValue as a view carved out of the spot bucket (buckets still sum to valueUsd). Legacy modes (default, disabled, dexAbstraction) keep separate ledgers — valueUsd = perp + spot + vault + staking.
• slices[i].spotBalances (Hyperliquid) — per-coin spot balances (coin, total, hold, usd). An unpriced non-zero balance makes the snapshot fail rather than silently understating NAV. Powers a Balances tab from the same call. Raw shape also available via GET /v1/hyperliquid/info/spot-clearinghouse-state.
• slices[i].perpByDex (Hyperliquid) — per-dex perp equity view (dex = '' for the main perp, HIP-3 dexs by name) with accountValueUsd + unrealizedPnlUsd. Powers a reserve breakdown; raw per-dex state via GET /v1/hyperliquid/info/clearinghouse-state?dex=.
• summary.totalNavUsd is the cross-provider Total Assets — Σ per-slice navUsd. This is the correct grand total (no double-count); prefer it over any hand-rolled sum of totalValueUsd/totalAvailableUsd.
• summary.totalValueUsd sums slices' valueUsd (provider-specific holdings value). Kept as a breakdown; slices with valueUsd: null are excluded but still counted in slices. providersReporting is the count of slices that contributed. Not the grand total — use totalNavUsd.
• summary.totalAvailableUsd sums idle/withdrawable cash (availableUsd) across providers — HL withdrawable + PM idle collateral. A liquidity breakdown; do not add it to totalValueUsd for a grand total (that double-counts HL) — use totalNavUsd.
• schemaVersion=1 / complete=true identify the authoritative snapshot contract. providersReporting always equals providersRequested on 200.
• warnings[] is retained for response compatibility and is empty on a successful snapshot. Any critical provider failure returns 502 instead of a partial response.
• fetchedAt is when the server completed the fan-out. Both legs are fetched in parallel via Promise.allSettled; the slower one bounds the total response time.

Error responses#

A 502 response identifies only the affected provider and a stable code:

json{
  "code": "portfolio_snapshot_incomplete",
  "message": "Unable to produce a complete portfolio snapshot",
  "failures": [{ "provider": "hyperliquid", "code": "provider_snapshot_unavailable" }]
}

Raw upstream errors, transport details, and URLs are logged server-side and are never included in the public response.

Worked example#

bash# A wallet active on both Polymarket + HL perps
curl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/portfolio/legacy?user=0xabc...&provider=polymarket,hyperliquid"

jsonc{
  "user": "0xabc...",
  "providers": ["polymarket", "hyperliquid"],
  "slices": [
    {
      "provider": "polymarket",
      "address": "0xabc...",
      "native": [
        {
          "conditionId": "0xCONDITION_ID",
          "outcome": "YES",
          "size": "150.00",
          "avgPrice": "0.62",
          "currentValue": "93.00",
        },
      ],
      "valueUsd": 93.0,
      "availableUsd": 40.0,
      "navUsd": 133.0,
      "note": null,
    },
    {
      "provider": "hyperliquid",
      "address": "0xabc...",
      "native": {
        "assetPositions": [
          {
            "type": "oneWay",
            "position": {
              "coin": "BTC",
              "szi": "0.5",
              "entryPx": "65000",
              "positionValue": "33850.5",
              "unrealizedPnl": "350.78",
            },
          },
        ],
        "marginSummary": { "accountValue": "12450.78", "totalNtlPos": "33850.5" },
        "withdrawable": "8400.21",
        "time": 1779163200000,
      },
      // unifiedAccount: the 12100.00 margining the BTC position is held on the
      // spot balance, so it's excluded from `spot` (available 0) and counted
      // once via `perp` = the full accountValue. Nothing counts twice.
      "valueUsd": 12450.78,
      "availableUsd": 8400.21,
      "navUsd": 12450.78,
      "buckets": [
        { "kind": "perp", "usd": 12450.78 },
        { "kind": "spot", "usd": 0 },
        { "kind": "vault", "usd": 0 },
        { "kind": "staking", "usd": 0 },
      ],
      "accountMode": "unifiedAccount",
      "note": null,
    },
  ],
  "summary": {
    "totalNavUsd": 12583.78,
    "totalValueUsd": 12543.78,
    "totalAvailableUsd": 8440.21,
    "providersReporting": 2,
  },
  "warnings": [],
  "fetchedAt": "2026-05-19T07:00:00.000Z",
}

Note how valueUsd (12450.78) is not native.marginSummary.accountValue plus spot — on a unifiedAccount wallet the perp margin already sits on the spot balance, so the buckets sum to the same total the HL app shows.

When the same wallet has no Polymarket activity:

jsonc{
  "user": "0xabc...",
  "providers": ["polymarket", "hyperliquid"],
  "slices": [
    { "provider": "polymarket",  "address": "0xabc...", "native": [],     "valueUsd": null, "availableUsd": 40.0, "navUsd": 40.0, "note": null },
    { "provider": "hyperliquid", "address": "0xabc...", "native": { ... }, "valueUsd": 12450.78, "availableUsd": 8400.21, "navUsd": 12450.78, "note": null }
  ],
  "summary": { "totalNavUsd": 12490.78, "totalValueUsd": 12450.78, "totalAvailableUsd": 8440.21, "providersReporting": 1 },
  "warnings": [],
  "fetchedAt": "2026-05-19T07:00:00.000Z"
}

valueUsd: null + empty native[] is the canonical "no positions" shape — not an error. summary ignores the null and the total still makes sense.

NAV time series (by address)#

GET /v1/portfolio/nav is a deprecated compatibility view over GET /v1/portfolio/performance. It performs no provider or node calls. A complete Performance checkpoint remains authoritative. If that cross-provider checkpoint is unavailable, each provider may independently return its validated durable last-good NAV; this never creates a partial aggregate. New consumers must read /v1/portfolio/performance directly for aggregate decisions.

Only a provider address already bound to the caller's organization may create a short-lived refresh hint, and that hint targets only the requested NAV window. Unbound addresses are cache-only and omit internal attempt/retry scheduling metadata. PM observation fallback is capped at 2,000 recent points; ALL therefore reports partial history rather than claiming an unbounded archive. HL NAV snapshots are also capped at 2,000 points; a legacy oversized ALL snapshot is truncated and explicitly downgraded to partial coverage.

Request#

bashcurl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/portfolio/nav?user=0xabc...&window=1M"

Query parameters#

Response#

jsonc{
  "window": "ALL",
  "providers": ["hyperliquid"],
  "series": [
    {
      "provider": "hyperliquid",
      "address": "0x1234abcd0000000000000000000000000000abcd",
      "source": "performance_projection",
      "quality": "authoritative", // | "degraded"
      "points": [
        { "t": 1782259200, "navUsdc": 10250.42, "netDepositsUsdc": 10000 },
        { "t": 1782345600, "navUsdc": 10480.13, "netDepositsUsdc": 10000 },
      ],
      "availability": {
        "dataStatus": "fresh", // | cached_fresh | cached_stale | unavailable
        "reason": null,
        "observedAt": "2026-07-08T09:59:00.000Z",
        "lastSuccessAt": "2026-07-08T09:59:00.000Z",
        "refreshAttemptedAt": "2026-07-08T09:59:00.000Z",
        "nextRetryAt": null,
        "nextRefreshAt": "2026-07-08T10:04:00.000Z",
        "source": "performance_projection",
      },
      // "note": "..."  // optional caveat (e.g. PM deposit steps as PnL steps)
    },
  ],
  "warnings": [], // per-provider upstream failures (never a 5xx)
  "asOf": "2026-07-08T10:00:00.000Z",
}

When Performance is unavailable, source may be hl_grid_primary or pm_nav_observations. cached_stale points are display-only: show lastSuccessAt and never use them as a fresh total, ranking input, or merged portfolio value.

• t = unix seconds, ascending. navUsdc = account value (USD) at t.
• netDepositsUsdc is the checkpointed cumulative cash-flow basis for the same provider cut.
• source is always performance_projection in this compatibility response.
• quality is authoritative only when the Performance window is ready; otherwise the provider envelope is degraded and empty.

Cumulative PnL time series#

GET /v1/portfolio/pnl is a deprecated compatibility view over GET /v1/portfolio/performance. It performs no provider or node calls. NAV and PnL are derived from one immutable Performance epoch. New consumers must read the canonical Performance contract directly.

Request#

bashcurl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/portfolio/pnl?user=0xabc...&window=1M"

Query parameters#

Response#

With window (single):

jsonc{
  "window": "1M",
  "providers": ["polymarket", "hyperliquid"],
  "series": [
    {
      "provider": "polymarket",
      "address": "0xabc...",
      "bound": true,
      "source": "performance_projection",
      "points": [
        { "t": 1779076800, "pnl": 0 },
        { "t": 1779080400, "pnl": 12.5 },
        { "t": 1779084000, "pnl": 9.8 },
      ],
    },
    {
      "provider": "hyperliquid",
      "address": "0xdef...",
      "bound": false,
      "source": "performance_projection",
      "points": [
        { "t": 1779076800, "pnl": 0 },
        { "t": 1779080400, "pnl": -40.0 },
        { "t": 1779084000, "pnl": 120.3 },
      ],
    },
  ],
  "merged": [
    { "t": 1779076800, "pnl": 0 },
    { "t": 1779080400, "pnl": -27.5 },
    { "t": 1779084000, "pnl": 130.1 },
  ],
  "warnings": [],
  "asOf": "2026-05-19T07:00:00.000Z",
}

With windows=1D,ALL (batched) — each series carries a byWindow map. HL and snapshot slices are window-anchored; PM slices remain account-cumulative. Additive mergedByWindow is safely normalized per window. Legacy merged keeps its cross-provider, all-or-nothing semantics:

jsonc{
  "windows": ["1D", "ALL"],
  "providers": ["hyperliquid"],
  "series": [
    {
      "provider": "hyperliquid",
      "address": "0xdef...",
      "bound": true,
      "byWindow": {
        "1D": {
          "source": "performance_projection",
          "status": "ready",
          "points": [
            { "t": 1779076800, "pnl": 0 },
            { "t": 1779080400, "pnl": 12.3 },
          ],
        },
        "ALL": {
          "source": "performance_projection",
          "status": "ready",
          "points": [
            { "t": 1777000000, "pnl": 0 },
            { "t": 1779080400, "pnl": -40.0 },
          ],
        },
      },
    },
  ],
  "merged": null,
  "mergedByWindow": {
    "1D": [
      { "t": 1779076800, "pnl": 0 },
      { "t": 1779080400, "pnl": 12.3 },
    ],
    "ALL": [
      { "t": 1777000000, "pnl": 0 },
      { "t": 1779080400, "pnl": -40.0 },
    ],
  },
  "warnings": [],
  "asOf": "2026-05-19T07:00:00.000Z",
}

Data-source policy#

• series[i].source is performance_projection for both providers.
• All provider and merged points are selected from one epoch/generation and share its finalized dataThrough cut.
• status: unavailable and empty points mean checkpoint coverage is not proven; they never mean zero PnL.
• canonical / canonicalByWindow remains the compatibility safety envelope. The canonical endpoint is /v1/portfolio/performance.
• warnings[] carries projection coverage failures; asOf is the adapter completion timestamp, not a provider observation time.

Hyperliquid rollup across sub-providers#

A wallet can be bound under any of the three Hyperliquid deployments (hyperliquid_perp, hyperliquid_hip4, hyperliquid_dex). When an org has multiple HL bindings for the same EOA, the customer-facing PnL surfaces (/v1/me/pnl and the portal tables) treat them as a single "Hyperliquid" family:

• Filter family-wide. /v1/me/pnl?provider=hyperliquid expands to all three HL sub-providers server-side; applied.provider echoes back the family label 'hyperliquid' so the chip selection round-trips intact.
• Per-sub-provider breakdown still available. Pass ?groupBy=provider (without a provider= filter) to see one row per fine-grained provider — useful when you actually want to attribute PnL back to perp vs hip4 vs dex. The portal collapses these visually into one "Hyperliquid" row; raw API consumers see the unrollup'd data.
• Storage stays fine-grained. customer_wallets.provider keeps the sub-provider enum; binding via provider=hyperliquid canonicalizes to hyperliquid_perp on the way in. resolveOrgByAddress matches fills across every HL sub-provider, so a single binding covers perp + hip4 + dex without duplicate rows.

The deprecated /v1/portfolio/legacy endpoint above is already family-flat — it returns one slices[i] per family (polymarket, hyperliquid), so there is no sub-provider exposure here. The rollup notes apply to /v1/me/pnl and the portal PnL pages.

Quota#

This endpoint is metered under the portfolio.read SKU. Each successful response counts as 1 unit. Per-tier daily caps live in the rate limits page.