Vault HTTP API

Public vault endpoints return indexed state and history. Capital transactions are wallet-signed. Operator commands go over the authenticated /vault WebSocket session.

Base URL and types

Devnet: https://devnet-api.acta.markets/api/v1. Beta: https://beta-api.acta.markets/api/v1.

Addresses are base58 strings. Token amounts, share amounts, large counters and Unix-second timestamps are decimal strings unless a field is listed as a JSON number. Share prices and the high-water mark use a scale of 1_000_000_000. Parse exact values with BigInt or another integer-safe representation.

Basis-point fields are JSON numbers. 100 basis points is 1%. Percent-return fields are JSON numbers in percent. A nullable field is null when the value is not available.

Vault list and detail

• GET /vaults returns { "vaults": Vault[] }.
• GET /vaults/{pda} returns one Vault object.

The list has no pagination. Optional query delegate=<pubkey> returns only vaults that key can operate as delegate: it is the primary_delegate and holds an unexpired delegate grant. A value that is not a base58 pubkey returns 400 invalid_delegate. Apply other filters on the client.

Closed vaults are left out of the list. Detail for a closed or unknown vault returns 404. History routes still serve closed vaults.

Vault fields

policy contains the numeric fields max_open_positions, max_rebalance_drift_bps and min_main_liquidity_bps.

projection contains version and slot as strings, transaction_index and event_index as numbers, and signature as a string. Balances carry their own timestamps in balance_updated_at and balance_chain_slot.

performance is one of:

• { "status": "unavailable" }
• { "status": "no_track_record" }
• status: "short_track_record" with cycles_completed, last_cycle_return_pct, cumulative_return_pct as numbers and track_record_secs as a string.
• status: "annualized" with the same fields plus numeric annualized_return_pct.

Annualization needs at least 30 days of completed-cycle history. Shares, equity and fees explains boundary equity, share price and live share ownership.

Position memberships

GET /vaults/{pda}/positions

The response is { "positions": VaultPosition[], "next_cursor": string | null }.

A dual-vault position has one chain position and a role-specific membership for each participating vault.

Cycles

GET /vaults/{pda}/cycles?limit=50&cursor=...

limit defaults to 50 and accepts 1–200. The response is { "cycles": VaultCycle[], "next_cursor": string | null }.

An unfinished cycle can have valuation data without a completed-cycle return. Read capital_generation from vault detail.

Pending request queues

• GET /vaults/{pda}/deposit-requests
• GET /vaults/{pda}/withdraw-requests

Both accept limit (default 50, range 1–100) and an optional cursor. Both return { "requests": Request[], "next_cursor": string | null }.

A deposit request contains wallet, amount, created_at as strings and nullable string transaction_signature. A withdrawal request contains wallet, shares, created_at as strings and nullable string transaction_signature.

Completed payouts are in depositor history.

Depositor state

• GET /vaults/{pda}/depositors/{wallet} returns one DepositorState.
• GET /depositors/{wallet} returns { "wallet": string, "vaults": DepositorState[] }.

deposit_request contains string amount, string created_at and nullable string transaction_signature. withdraw_request contains string shares, string created_at and nullable string transaction_signature.

totals contains string fields shares_minted, shares_burned, total_deposited, total_withdrawn and last_activity_at.

For a valid wallet with no indexed activity, the single-vault route returns vault and wallet with the three optional fields set to null. The cross-vault route can return an empty vaults array.

The totals sum indexed capital activity. Shares can move between wallets, so read current balances from the wallet's token accounts on Solana.

Depositor history

• GET /vaults/{pda}/depositors/{wallet}/history
• GET /depositors/{wallet}/history

Both accept limit (default 50, range 1–200) and an optional opaque cursor. The response is { "events": DepositorEvent[], "next_cursor": string | null }.

A final redemption can pay out the second asset. second_amount records it apart from the main-asset amount.

Pagination example

Fetch the first page, then pass the returned cursor back:

curl 'https://devnet-api.acta.markets/api/v1/vaults/<vault-pda>/cycles?limit=50'
curl --get 'https://devnet-api.acta.markets/api/v1/vaults/<vault-pda>/cycles' \
  --data-urlencode 'limit=50' \
  --data-urlencode 'cursor=<returned-next_cursor>'

next_cursor: null is the last page. Send the cursor unchanged to the same route with the same filters, URL-encoded.

Errors and freshness

List and detail are served from memory. Other routes read the database. List, detail, positions, cycles and pending queues can be cached for five seconds.

Errors use { "error": "Human-readable message", "code": "error_code" }.

HTTP data changes only after the backend indexes a transaction, so read chain accounts right after you submit one. See Backend services and data and Transaction recovery.