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/points

Vault-scoped gmPoints accumulated by a wallet. The response includes only vaults visible to the API key; Project Zero keys should be explicitly restricted to the applicable Project Zero vault ids.

Param	Description
wallet	Wallet pubkey (required).

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

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

Field	Description
vaultId, vaultName	Vault identity.
points	Whole gmPoints accumulated from that vault's award ledger.
lastAwardedAt	ISO timestamp of the latest award for this wallet and vault, or null.

Points are awarded once per daily vault run. At a 1× campaign rate, the base award is one point per whole dollar of the wallet's current vault-share value; configured vault multipliers and referral adjustments are then applied. totalPoints sums only the returned vaults. Quest points and quest referral kickbacks are intentionally excluded because they are not attributable to a vault.

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