Skip to main content
The Wallet API reads Swig wallet state and manages saved wallet policy templates. Most routes are API-key guarded; two are the public client boundary used by wallet front ends. API-key reads consume the API-request allowance. See Swig Query: wallets and tokens for the query catalog and quotas, and public reads for lookup/status accounting.

Routes

For the API-key routes, send:
Read operations are safe to retry. Policy creation is a write and has no idempotency key; reconcile an uncertain result before retrying. The public lookup boundary is also a POST. Developer-portal admin endpoints are intentionally omitted from this reference.

Role templates

These operations are defined in wallet/api_wallet.proto on wallet.v1.WalletService. Organization and actor come from the verified project API key. See the SDK examples.
name and a nonempty permissions array are required. Omit authority for a TBD key, or supply one direct authority, for example { "ed25519": { "publicKey": "..." } }; secp256k1 and secp256r1 are also supported. Use stored PascalCase permission types and exact decimal strings for amounts and recurring slot windows. The TypeScript SDK converts its typed inputs. Read resources contain id, name, permissions, keySource, and authority when stored. keySource is WALLET_POLICY_KEY_SOURCE_AT_CREATION or WALLET_POLICY_KEY_SOURCE_STORED. Updates keep the same role ID and immediately change what future wallet creations resolve.

Wallet templates

A wallet resource contains id, name, description, initialRole, additionalRoles, and optional rentClaimer and recovery. It resolves the latest referenced roles in a single snapshot. Wallet membership updates do not edit shared roles. Neither role nor wallet template edits change existing on-chain wallets. There are no versions, network filters, or pagination. Both update RPCs replace the supplied definition. Omitted optional fields clear those settings. All RPCs use operation-specific request/response messages; shared resources are defined in wallet/policy.proto. Empty protobuf list fields may be omitted in ProtoJSON; the SDK returns empty arrays. Creation through POST /transaction/wallet/create uses the wallet template ID as policyId. Bind TBD roles with roleAuthorities: [{ roleTemplateId, authority }] or initialUser for the initial role. Supply guardianAuthority for TBD recovery. The response includes templateSetup: the resolved template, all authorities, and optional guardianAuthority. Additional roles and settings remain pending until their transactions are authorized and confirmed. See template creation.

Get USD balance

GET /wallet/swig/{swig_config_address}/balance/usd Query parameters: Response fields:

List token balances

GET /wallet/swig/{swig_config_address}/token-balances Query parameters: Response fields: Each balance carries mintAddress, tokenProgram, tokenSymbol, tokenName, decimals, amountRaw, uiAmount, usdPrice, usdValue, and assetKind. assetKind is the ProtoJSON enum ASSET_KIND_TOKEN, ASSET_KIND_NATIVE_SOL, or ASSET_KIND_UNSPECIFIED. Use amountRaw for arithmetic; it is the exact integer amount as a string.

List token transactions

GET /wallet/swig/{swig_config_address}/token-transactions Query parameters: Each entry carries transactionSignature, slot, blockTime, ownerAddress, walletAddress, isSubaccount, tokenAccountAddress, mintAddress, tokenProgram, direction, amountRaw, decimals, uiAmount, usdPrice, usdValue, tokenSymbol, tokenName, and assetKind. direction is an inflow or outflow relative to the wallet. assetKind uses the same ProtoJSON enum values as token balances.

List roles

GET /wallet/swig/{swig_config_address}/roles Query parameters: Response fields: Each role carries roleId, authorityType, authorityValue, and actions. Each action carries actionIndex, actionCode, and actionData. authorityValue is the authority’s public key material, and actionData is a raw per-action object whose shape depends on the action. Interpret both against the protocol permissions model. Use this endpoint to confirm which authorities currently control a wallet and what each one is allowed to do.

DEX activity

A Swig’s indexed DEX transactions and liquidity positions are read through the DEX API.

Get policy

GET /wallet/policies/{policy_id} reads a policy visible to the API-key organization. This compatibility response retains the initial-role and guardian fields and includes initialUserLabel and additionalUsers. Prefer the template endpoints above for complete current layouts.

Public client boundary

POST /wallet/swig/lookup and GET /wallet/swig/status sit on the public client boundary rather than behind an API key. They exist so a wallet front end can resolve and check a Swig without holding a server credential. Do not treat them as a substitute for the API-key reads above.

Not part of this reference

Some paths exist in the backend but are not usable integration surfaces. In particular, /wallet/swig/auth/check and /wallet/swig/session are backend stubs. Do not build against them.