Vault endpoints

These endpoints read vault-level and vault-scoped data. All require a read-scope API key. Replace VAULT_ID with a registered vault pubkey (examples use GPZW7ihHMMfZg5eNDmn376mwVzBKHh867vdWmjvNvYPK).

GET /api/agents

Returns the catalog of vault agents, filtered to the key's vault scope. On-chain program internals are deliberately not exposed.

curl "https://app.gma.fi/api/agents" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response data is an array of AgentSummary:

Field	Description
vaultId	Vault pubkey (base58).
slug	Agent slug/id.
name	Internal vault name.
strategyType	Strategy category.
display	{ title, description, icon, color, riskLevel, riskPercentage }.
assets	Deposit asset token: { symbol, mint, decimals, imageUrl }.
shares	Share token: { symbol, mint, decimals, imageUrl }.
capacityLimit	Deposit cap in asset lamports (raw), or null.

GET /api/vault/{vault_id}/nav

Current NAV and pricing, read from the on-chain LpVault account (cached ~10s).

curl "https://app.gma.fi/api/vault/GPZW7ihHMMfZg5eNDmn376mwVzBKHh867vdWmjvNvYPK/nav" \
  -H "Authorization: Bearer YOUR_API_KEY"

Field	Description
vaultId, vaultName	Vault identity.
agentAuthority	On-chain fund authority (agent wallet owning the vault's protocol positions), or null.
sharePrice	Asset per share.
totalShares	Token amount object { mint, symbol, amount, decimals, uiAmount }.
nav	Net asset value (TVL) as a token amount object.
capacityLimit	Token amount object, or null.
updatedAt	ISO timestamp of the on-chain read.

GET /api/vault/{vault_id}/stats

Aggregated headline statistics.

curl "https://app.gma.fi/api/vault/GPZW7ihHMMfZg5eNDmn376mwVzBKHh867vdWmjvNvYPK/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

Field	Description
vaultId, sharePrice	Vault identity and price.
nav, tvl	NAV in asset units; TVL in USD (nav × spot, or nav for USDC vaults).
capacity	Human capacity limit, or null.
depositors, volume24h, pending	Depositor count, 24h volume, pending intentions.
performanceFeeBps	Performance fee in basis points.
withdrawalFeeBps, withdrawalFeeEnforced	Withdrawal fee bps and whether it is enforced.
hourlyNetWithdrawalCapBps, dailyNetWithdrawalCapBps	Net withdrawal guardrails (bps).
withdrawalLimits	Current withdrawal-limit state, or null.
currentAPY, solverPredictedAPY, realizedAPY, predictedAPY, historicalAPY	The five APY metrics. Fractional (0.0824 = 8.24%); nullable.
totalPnL	Total vault PnL in asset units; nullable.

GET /api/vault/{vault_id}/allocations

Current actual holdings. By default the verbose solver/leverage internals are stripped; ?detail=full includes them.

curl "https://app.gma.fi/api/vault/GPZW7ihHMMfZg5eNDmn376mwVzBKHh867vdWmjvNvYPK/allocations?detail=full" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response data is { allocations: [...] }. Each allocation:

Field	Description
provider, tokenName, tokenMint, productId	Position identity (nullable).
ratio	Deployed-balance ratio of the position.
balance	Human balance.
predictedApy	Raw predicted APY at the position's actual leverage (fractional).
displayApy	Clamped combined APY for display, or null when the leg's rate is implausible.
leverage	Display leverage, or null.
marketType	Market type, or null.
isIdle	Whether the position is idle.

With ?detail=full, each allocation additionally includes: hasRate, historicApyMean, historicApyStd, solverPredictedApy, nativeYieldApy, leverageIsTarget, leverageSource, actualLeverage, targetLeverage, and a properties object.

GET /api/vault/{vault_id}/history

Time-series for a single vault metric. metric is required; range normalizes to 24h|7d|30d|90d|1yr|all (unknown ⇒ 7d).

Param	Values
metric	share-price, tvl, apy, realized-apy, historical-apy (required).
range	24h, 7d, 30d, 90d, 1yr, all (default 7d).

curl "https://app.gma.fi/api/vault/GPZW7ihHMMfZg5eNDmn376mwVzBKHh867vdWmjvNvYPK/history?metric=apy&range=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response data is { metric, range, points: [...] }. Each point is { date (ISO), value (number|null), usdValue? (number|null) }. usdValue is present only for share-price. The apy, realized-apy, and historical-apy metrics return fractional values.

GET /api/vault/{vault_id}/pnl-history

Per-user PnL time series for one vault. wallet is required; a wallet-bound key may only query its own wallet.

Param	Values
wallet	Wallet pubkey (required).
range	24h, 7d, 30d, 90d, 1yr, all (default 7d).

curl "https://app.gma.fi/api/vault/GPZW7ihHMMfZg5eNDmn376mwVzBKHh867vdWmjvNvYPK/pnl-history?wallet=YOUR_WALLET_PUBKEY&range=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response data is { wallet, vaultId, range, points: [...] }. Each point:

Field	Description
date	ISO timestamp.
shares	Human shares held at the snapshot.
sharePrice	Native value per share.
value	Asset value: shares × sharePrice.
costBasis	Cumulative deposited − redeemed, in asset units.
pnl	value + redeemed − deposited, in asset units.
pnlPct	PERCENT (pnl / deposited × 100) — not fractional.

Values are asset-denominated (USD for USDC vaults); the latest point reconciles with /api/positions.

GET /api/vault/{vault_id}/portfolio-history

Per-rebalance snapshots showing what changed in the vault's holdings.

Param	Values
limit	Snapshot count, 1..100 (default 10).

curl "https://app.gma.fi/api/vault/GPZW7ihHMMfZg5eNDmn376mwVzBKHh867vdWmjvNvYPK/portfolio-history?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response data is an array of PortfolioHistoryEntry (ISO dates, human balances, the holding product_kind discriminator, and a solver-target block).

PERCENT warning. In every entry, solverTarget.predictedApy, and each target's targetPct and predictedApy, are percent (0..100), not fractional — matching the in-app history drawer. Do not divide by 100 twice or multiply a fractional value here.

GET /api/vault/{vault_id}/rebalances

Timestamps at which the agent's portfolio composition changed within the range.

Param	Values
range	24h, 7d, 30d, 90d, 1yr, all (default 7d).

curl "https://app.gma.fi/api/vault/GPZW7ihHMMfZg5eNDmn376mwVzBKHh867vdWmjvNvYPK/rebalances?range=7d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response data is { range, points: [{ date (ISO) }] }.

Next: Wallet endpoints