> ## Documentation Index
> Fetch the complete documentation index at: https://tavryn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions and Metrics: USDC Payments and Savings Data

> Query USDC payment records, aggregated savings, governance stats, and on-chain transaction status. Covers the full metrics response shape and CSV export.

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.

**id** `string`

UUID uniquely identifying this transaction within Tavryn's database.

**businessId** `string`

UUID of the business that owns this transaction.

**businessName** `string`

Display name of the business. `"Unknown"` if the business record cannot be resolved.

**vendorName** `string`

Name of the vendor receiving the payment. `"Direct Vendor"` if the vendor record is unresolved.

**amount** `number`

The USDC amount settled in this transaction. Denominated in whole USD (not micro-units). Example: `29760` means \$29,760 USDC.

**currency** `string`

Currency denomination. Always `"USDC"` unless overridden on the transaction record.

**status** `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

**escrowAddress** `string | null`

The Arc network escrow contract address used for this payment. `null` if not yet assigned.

**txHash** `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`.

**isSimulated** `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.

**createdAt** `string`

ISO 8601 timestamp of when the transaction record was first created in Tavryn's database.

> [!NOTE]
>
> 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**

**realOnly** `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.

**format** `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**

**metrics** `object`

**metrics fields**

**realOnly** `boolean`

Reflects the `realOnly` filter value used for this request.

**generatedAt** `string`

ISO 8601 timestamp of when the metrics snapshot was computed.

**businesses** `object`

**businesses fields**

**totalCount** `number`

Total number of businesses in scope.

**realCount** `number`

Number of live (non-demo) businesses.

**demoCount** `number`

Number of demo or simulated businesses.

**list** `array`

Array of business summary objects, each with `id`, `name`, `walletAddress`, `treasuryBalance`, `contractsCount`, `totalSpend`, `totalSavings`, and `createdAt`.

**usdcVolume** `object`

**usdcVolume fields**

**escrowed** `number`

Total USDC escrowed across all qualifying transactions, in USD.

**released** `number`

Total USDC released from escrow to vendors, in USD.

**refunded** `number`

Total USDC refunded back to the business, in USD.

**inFlight** `number`

USDC currently held in escrow awaiting release or verification, in USD.

**failedOrDisputed** `number`

USDC in failed or disputed transactions, in USD.

**currency** `string`

Always `"USDC"`.

**savings** `object`

**savings fields**

**negotiated** `number`

Sum of all negotiated savings across completed negotiation cycles, in USD.

**realized** `number`

Savings that have been realized through on-chain or off-chain settlement, in USD.

**offChainSavings** `number`

Subset of realized savings that were agreed off-chain without a blockchain payment, in USD.

**totalSpendAnalyzed** `number`

Sum of all current contract prices analyzed, in USD.

**savingsRatePct** `number`

Negotiated savings as a percentage of total spend analyzed, to one decimal place.

**contractsAndNegotiations** `object`

**contractsAndNegotiations fields**

**contractsTotal** `number`

Total contracts in scope.

**contractsOptimized** `number`

Contracts that have undergone at least one negotiation cycle.

**negotiationsRun** `number`

Total negotiation cycles initiated.

**negotiationsAccepted** `number`

Negotiations that reached an accepted outcome.

**negotiationsWalkedAway** `number`

Negotiations where the agent chose not to proceed.

**negotiationsActive** `number`

Negotiations currently in progress.

**governance** `object`

**governance fields**

**agentDecisionsCount** `number`

Total autonomous decisions logged to the agent audit trail.

**humanEscalationsCount** `number`

Total approval requests sent to human reviewers.

**humanApprovedCount** `number`

Escalations that were approved by a reviewer.

**humanRejectedCount** `number`

Escalations that were rejected by a reviewer.

**humanPendingCount** `number`

Escalations currently awaiting a reviewer decision.

**humanApprovalRatePct** `number`

Percentage of decided escalations that were approved, to one decimal place.

**reviewer** `object`

**reviewer fields**

**totalReviews** `number`

Total deal reviews submitted.

**agreedCount** `number`

Reviews with verdict `"agree"`.

**challengedCount** `number`

Reviews with verdict `"challenge"`.

**rejectedCount** `number`

Reviews with verdict `"reject"`.

**challengeRatePct** `number`

Percentage of reviews that were challenged or rejected, to one decimal place.

**efficiency** `object`

**efficiency fields**

**avgRoundsToClose** `number`

Average number of negotiation rounds across all closed negotiations.

**avgCycleTimeMinutes** `number`

Average time in minutes from negotiation start to transaction creation.

**receiptsCount** `number`

Number of active (non-revoked) savings receipts across all qualifying businesses.

**transactions** `array`

Array of transaction objects matching the current filter. Each object contains the full transaction shape described above.

**Example request — JSON**

```bash theme={null}
curl "https://tavryn.network/api/metrics"
```

**Example request — real transactions only, CSV download**

```bash theme={null}
curl "https://tavryn.network/api/metrics?realOnly=true&format=csv" \
  -o tavryn-metrics.csv
```

**Example JSON response**

```json theme={null}
{
  "metrics": {
    "realOnly": false,
    "generatedAt": "2026-04-01T12:00:00.000Z",
    "businesses": {
      "totalCount": 2,
      "realCount": 1,
      "demoCount": 1,
      "list": [
        {
          "id": "biz-uuid",
          "name": "Acme Corp",
          "walletAddress": "0xAbCd1234...",
          "treasuryBalance": 85000,
          "contractsCount": 4,
          "totalSpend": 120000,
          "totalSavings": 18400,
          "createdAt": "2026-01-15T09:00:00.000Z"
        }
      ]
    },
    "usdcVolume": {
      "escrowed": 60000,
      "released": 54000,
      "refunded": 0,
      "inFlight": 6000,
      "failedOrDisputed": 0,
      "currency": "USDC"
    },
    "savings": {
      "negotiated": 18400,
      "realized": 14200,
      "offChainSavings": 2100,
      "totalSpendAnalyzed": 120000,
      "savingsRatePct": 15.3
    },
    "contractsAndNegotiations": {
      "contractsTotal": 4,
      "contractsOptimized": 3,
      "negotiationsRun": 5,
      "negotiationsAccepted": 4,
      "negotiationsWalkedAway": 1,
      "negotiationsActive": 0
    },
    "governance": {
      "agentDecisionsCount": 24,
      "humanEscalationsCount": 3,
      "humanApprovedCount": 2,
      "humanRejectedCount": 1,
      "humanPendingCount": 0,
      "humanApprovalRatePct": 66.7
    },
    "reviewer": {
      "totalReviews": 5,
      "agreedCount": 4,
      "challengedCount": 1,
      "rejectedCount": 0,
      "challengeRatePct": 20.0
    },
    "efficiency": {
      "avgRoundsToClose": 2.8,
      "avgCycleTimeMinutes": 4
    },
    "receiptsCount": 3,
    "transactions": [
      {
        "id": "c9a1f820-1234-4d56-a789-bc3d0e001f22",
        "businessId": "biz-uuid",
        "businessName": "Acme Corp",
        "vendorName": "Datadog, Inc.",
        "amount": 29760,
        "currency": "USDC",
        "status": "completed",
        "escrowAddress": "0x673B3a5B1f...",
        "txHash": "0x4a3b2c1d...",
        "isSimulated": false,
        "createdAt": "2026-03-28T11:02:44.000Z"
      },
      {
        "id": "d1e2f3a4-5678-4b90-c123-de4f56789012",
        "businessId": "biz-uuid",
        "businessName": "Acme Corp",
        "vendorName": "Slack Technologies",
        "amount": 6912,
        "currency": "USDC",
        "status": "completed",
        "escrowAddress": null,
        "txHash": "0xsimulated_slack_8ab3c",
        "isSimulated": true,
        "createdAt": "2026-03-30T10:00:00.000Z"
      }
    ]
  }
}
```

**Error responses**

| Status | Condition |
| - | - |
| `400` | Invalid `realOnly` or `format` query parameter value |
| `500` | Internal error computing metrics |

***

## Double-Payment Protection

> [!TIP]
>
> 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:

```text theme={null}
Negotiation finalized
        │
        ▼
   [pending]  ←── Circle transfer initiated
        │
        ▼ Circle webhook: CONFIRMED / COMPLETE / SUCCESS
   [funded]   ←── Circle confirmed; Arc settlement in progress
        │
        ▼ Arc block finalized
  [completed] ←── On-chain settlement confirmed
```

If Circle reports `FAILED`, `CANCELLED`, or `REJECTED` at any stage, the transaction moves directly to `[failed]` and no funds are moved.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.