Wallet endpoints

These endpoints are keyed by a wallet pubkey. Reads need a read-scope key; recording activity needs write. A wallet-bound key may only act on its bound wallet.

GET /api/positions

Wallet holdings across every vault in the key's scope.

Param	Description
wallet	Wallet pubkey (required).

curl "https://app.gma.fi/api/positions?wallet=YOUR_WALLET_PUBKEY" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response data is { wallet, vaults: [...] }. Each vault entry:

Field	Description
vaultId, vaultName	Vault identity.
shares	Token amount object { mint, symbol, amount, decimals, uiAmount }.
sharePrice	Current share price.
currentValue, depositedValue, redeemedValue, totalReturn	Token amount objects, in asset units.
totalReturnPercentage	Return percentage.
pendingWithdrawal	{ shares, estimatedValue }, both token amount objects.

GET /api/history

Deposit/withdrawal history for a wallet in one vault.

Param	Description
wallet	Wallet pubkey (required).
vault_id	Registered vault pubkey (optional; defaults to the default vault).
limit	Max results, default 50, capped at 100.
offset	Pagination offset, default 0.

curl "https://app.gma.fi/api/history?wallet=YOUR_WALLET_PUBKEY&vault_id=GPZW7ihHMMfZg5eNDmn376mwVzBKHh867vdWmjvNvYPK&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response data is { wallet, vaultId, transactions: [...], hasMore, pagination }. Each transaction:

Field	Description
intentId	Interaction intent id.
type	deposit or withdrawal.
status	Intent status.
requestedAt, completedAt	ISO timestamps (completedAt may be null).
amountUsdc	Asset amount (human).
sharesAmount	Shares (human).
signatures	{ request, complete } transaction signatures (nullable).

pagination is { limit, offset, nextOffset } (nextOffset is null when there are no more results).

POST /api/history

Records a confirmed, wallet-authored vault interaction immediately, so partner-submitted transactions do not wait for the periodic backfill. Requires a write-scope key. Send this right after a deposit or withdraw transaction confirms.

The confirmed transaction on-chain is the sole authority: type, amount, mints, status, and balance changes are all derived from chain data and are never accepted from the request body. Only these body fields are allowed (any other field is rejected):

Field	Description
wallet	Wallet pubkey (required).
vault_id	Registered vault pubkey (required).
signature	Confirmed Solana transaction signature (required).
withdrawal_reservation_id	UUID from the withdraw builder (optional; carry it when recording a queued withdrawal initiate).

curl -X POST "https://app.gma.fi/api/history" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"wallet":"YOUR_WALLET_PUBKEY","vault_id":"GPZW7ihHMMfZg5eNDmn376mwVzBKHh867vdWmjvNvYPK","signature":"CONFIRMED_TRANSACTION_SIGNATURE"}'

Response data:

Field	Description
wallet, vaultId, signature	Echo of the recorded interaction.
recorded	true when newly recorded.
duplicate	true when the same wallet/vault/signature was already recorded — an idempotent success (HTTP 200), treat it as success.
intentId	The interaction intent id, or null.

Error semantics worth handling:

• 409 "No pending withdrawal found for this claim" — record the confirmed initiate signature first, then retry the claim signature.
• 422 — the transaction is not found/unconfirmed/failed, or is not a recordable _gamma vault interaction.

Content-Type must be application/json; oversized bodies return 413.

Next: Transactions