Skip to main content

Wallets & Transactions API

Client wallet endpoints operate on the authenticated user's Arc Testnet user-controlled wallet.

Client wallet​

GET  /api/v1/client/wallet/
POST /api/v1/client/wallet/initialize/
POST /api/v1/client/wallet/sync/
GET  /api/v1/client/wallet/balance/

Initialize​

wallet/initialize/ either reports that a suitable Arc wallet already exists or returns a Circle wallet-creation challenge.

Current wallet characteristics:

Blockchain: ARC-TESTNET
Account type: SCA
Custody: user controlled
Purpose: client escrow

Sync​

wallet/sync/ verifies the Arc wallet against the authenticated Circle session and stores only authoritative public wallet metadata in Veyra.

Balance​

wallet/balance/ rechecks the user's Circle wallet and returns the current Arc Testnet USDC balance.

Client transaction tracking​

GET  /api/v1/client/transactions/
GET  /api/v1/client/transactions/{transaction_id}/
POST /api/v1/client/transactions/{transaction_id}/

The collection endpoint can be filtered by draft and purpose.

The detail GET reconciles transaction state. The detail POST is used after the browser completes a Circle challenge so Veyra can attach/resolve the Circle transaction and continue authoritative reconciliation.

What Veyra correlates​

A transaction record can correlate:

  • local Veyra transaction UUID;
  • idempotency key;
  • Circle challenge ID;
  • Circle transaction ID;
  • Circle reference ID;
  • Arc transaction hash;
  • Arc receipt/block information;
  • expected contract action;
  • expected commitment/calldata hash.

Why Circle "complete" is not enough​

For settlement-sensitive actions, Veyra validates the expected Arc transaction/receipt and resulting contract state.

A browser challenge result is not allowed to invent final onchain success.

Agent-owner wallet endpoints​

Agent operational-wallet and withdrawal actions belong to the owner-scoped agent API, not the client-wallet family. See Agents & Runtime.