Skip to main content
Transactions in Tavryn represent USDC payments executed on the Arc network via Circle’s Developer-Controlled Wallets infrastructure. Every time Tavryn’s autonomous agent finalizes a negotiation and releases escrow, a transaction record is created and updated as it progresses through Circle’s payment lifecycle — from pending initialization through funded (Circle confirmed) to completed (on-chain settled). You can query these records through the metrics endpoint, which returns the full transaction list alongside aggregated savings data, governance stats, and USDC volume breakdowns.

Transaction Object

All transaction records returned inside the metrics response share a common shape. Understanding each field helps you distinguish live on-chain activity from demo or testnet simulations.
string
UUID uniquely identifying this transaction within Tavryn’s database.
string
UUID of the business that owns this transaction.
string
Display name of the business. "Unknown" if the business record cannot be resolved.
string
Name of the vendor receiving the payment. "Direct Vendor" if the vendor record is unresolved.
number
The USDC amount settled in this transaction. Denominated in whole USD (not micro-units). Example: 29760 means $29,760 USDC.
string
Currency denomination. Always "USDC" unless overridden on the transaction record.
string
Current lifecycle status of the transaction. One of:
  • pending — initiated, awaiting Circle wallet funding
  • funded — Circle confirmed the transfer; waiting for on-chain finality
  • completed — fully settled on the Arc network
  • failed — Circle or on-chain execution failed; no funds moved
string | null
The Arc network escrow contract address used for this payment. null if not yet assigned.
string | null
The on-chain transaction hash on the Arc network. Only populated for real (non-simulated) transactions that have reached funded or completed status. null for simulated transactions or transactions still in pending.
boolean
true when the transaction is a mock or testnet-mode demonstration. Simulated transactions go through the full Tavryn workflow (negotiation, policy check, escrow logic) but do not spend real USDC and do not produce a live Arc explorer entry.
string
ISO 8601 timestamp of when the transaction record was first created in Tavryn’s database.
Simulated transactions display a “Simulated (testnet mock)” badge in the Tavryn dashboard and on public savings receipts. Their txHash values (when present) begin with 0xsimulated. Do not pass simulated txHash values to any on-chain verification tool.

GET /api/metrics

Returns aggregated savings metrics, USDC volume data, governance statistics, and the full list of transaction records. This is the primary endpoint for building dashboards, investor traction reports, and exportable summaries of Tavryn’s negotiation outcomes. Query parameters
boolean
When true (or 1), filters out all simulated/testnet transactions and returns only live on-chain payment records. Defaults to false (returns all transactions). Useful for investor-facing metrics that should exclude demo data.
string
Response format. json (default) returns the structured metrics object. csv triggers a file download with a filename in the format tavryn-traction-metrics-{filter}-{date}.csv.
Response fields
object
Example request — JSON
Example request — real transactions only, CSV download
Example JSON response
Error responses

Double-Payment Protection

Tavryn uses idempotency keys at the Circle API layer to prevent duplicate payments. If a network timeout causes Tavryn to retry a Circle transfer request, the idempotency key ensures Circle deduplicates the call server-side and returns the original transaction rather than initiating a second payment. You will never see two transactions for the same contract negotiation.

Transaction Status Flow

The diagram below shows the normal lifecycle of a Tavryn USDC transaction:
If Circle reports FAILED, CANCELLED, or REJECTED at any stage, the transaction moves directly to [failed] and no funds are moved.