> ## 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.

# Receipts API: Access Verified Savings Receipts

> Fetch, share, and manage publicly verifiable savings receipts. Receipts prove negotiated outcomes on-chain and are shareable without authentication.

Savings receipts are Tavryn's verifiable proof-of-outcome artifacts. Every time the agent completes a negotiation and settles a USDC payment, it generates a receipt — a lightweight public document that records the original price, the negotiated price, the realized savings, and (for real transactions) a link to the on-chain Arc settlement. Receipts are identified by a 128-bit random token and accessible at `/r/{token}` without any login required, making them easy to share with finance teams, auditors, or investors.

***

## Receipt Object

**token** `string`

32-character hex token (128 bits of entropy) that identifies this receipt. Used as the path parameter in the public receipt URL `/r/{token}`.

**service** `string`

Human-readable name of the SaaS or cloud service that was renegotiated. Example: `"Datadog Cloud Monitoring"`.

**category** `string`

Spend category of the contract. One of `software`, `cloud`, `contractors`, `infrastructure`, `legal`, or `marketing`.

**businessName** `string | null`

Name of the organization that achieved this saving. `null` if the business has disabled name visibility via the `showBusinessName` privacy flag.

**vendorName** `string | null`

Name of the vendor. `null` if vendor name visibility is disabled via `showVendorName`.

**oldPrice** `number`

The annual contract price before Tavryn's negotiation, in USD.

**newPrice** `number`

The negotiated annual price, in USD. This is the USDC amount settled on-chain.

**annualSavings** `number`

Calculated as `oldPrice − newPrice`. Always ≥ 0.

**savingsPct** `number`

Savings as a percentage of the original price, rounded to the nearest integer.

**roundsCount** `number`

Number of negotiation rounds the agent ran before reaching the final price.

**agentExplanation** `string`

Plain-language summary of how the agent reached this outcome, drawn from the audit log.

**policyChecklist** `array`

**policyChecklist items**

An array of policy gate results, each with:

**name** `string`

Name of the policy check. Examples: `"Policy Ceiling"`, `"Minimum Savings"`, `"On-Chain Escrow"`.

**passed** `boolean`

Whether this policy gate passed.

**detail** `string`

Human-readable explanation of the check result.

**verificationResult** `object`

**verificationResult fields**

**verified** `boolean`

Overall verification status.

**allPassed** `boolean`

`true` if every matched check passed.

**matchedChecks** `array of strings`

List of named checks that were verified. Example: `["Contract Price Matched", "Arc Settlement Completed"]`.

**arcExplorerUrls** `object`

**arcExplorerUrls fields**

**releaseTxUrl** `string | null`

Direct ArcScan link to the escrow release transaction. `null` for simulated receipts.

**escrowContractUrl** `string`

ArcScan link to the Tavryn escrow smart contract address.

**network** `string`

Network description. `"Arc Testnet (USDC-native EVM)"` for real transactions; `"Arc Testnet (Simulated Mock)"` for simulated ones.

**isSimulated** `boolean`

`true` when this receipt corresponds to a mock/testnet transaction that did not spend real USDC.

**releaseTxHash** `string | null`

The on-chain transaction hash of the escrow release. `null` for simulated receipts.

**createdAt** `string`

ISO 8601 timestamp of when the receipt was created.

***

## GET /api/receipts/{token}

Fetch the public view model for a single savings receipt. This endpoint is **publicly accessible** — no authentication is required. It is rate-limited to 60 requests per minute per IP address to prevent enumeration attacks.

> [!NOTE]
>
> For real (non-simulated) transactions, the `arcExplorerUrls.releaseTxUrl` field points directly to the ArcScan block explorer entry for the escrow release transaction. Anyone — including vendors, auditors, or investors — can independently verify that the payment occurred by visiting that URL. This on-chain verifiability is a core part of Tavryn's trust model.

**Path parameters**

**token** `string` *required*

The 32-character hex receipt token. You obtain this from the receipt record returned after a transaction completes, or from the `receiptUrl` field in a `createReceipt` response.

**Example request**

```bash theme={null}
curl https://tavryn.network/api/receipts/a1b2c3d4e5f6...
```

**Example response**

```json theme={null}
{
  "token": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
  "service": "Datadog Cloud Monitoring",
  "category": "cloud",
  "businessName": "Acme Corp",
  "vendorName": "Datadog, Inc.",
  "oldPrice": 37200,
  "newPrice": 29760,
  "annualSavings": 7440,
  "savingsPct": 20,
  "roundsCount": 3,
  "agentExplanation": "Autonomous procurement cycle finalized within enterprise policy limits.",
  "policyChecklist": [
    {
      "name": "Policy Ceiling",
      "passed": true,
      "detail": "New commitment ($29,760) within approved ceiling"
    },
    {
      "name": "Minimum Savings",
      "passed": true,
      "detail": "Generated $7,440 in realized annual savings (20%)"
    },
    {
      "name": "On-Chain Escrow",
      "passed": true,
      "detail": "Funded and executed through Arc smart escrow protocol in USDC"
    }
  ],
  "verificationResult": {
    "verified": true,
    "allPassed": true,
    "matchedChecks": [
      "Contract Price Matched",
      "Seat Allotment Verified",
      "Term Length Confirmed",
      "Arc Settlement Completed"
    ]
  },
  "arcExplorerUrls": {
    "releaseTxUrl": "https://arcscan.io/tx/0x4a3b2c1d...",
    "escrowContractUrl": "https://arcscan.io/address/0x673B3a...",
    "network": "Arc Testnet (USDC-native EVM)"
  },
  "isSimulated": false,
  "releaseTxHash": "0x4a3b2c1d...",
  "createdAt": "2026-03-30T10:00:00.000Z"
}
```

**Error responses**

| Status | Condition |
| - | - |
| `404` | Token not found, revoked, or does not exist — all cases return the same generic message to prevent token enumeration |
| `429` | Rate limit exceeded (60 req/min per IP). Check the `Retry-After` response header for reset time |

***

## PATCH /api/receipts/{token}

Update the privacy settings of an existing receipt or permanently revoke public access. Revoked receipts return `404` to all subsequent GET requests — even with the original token.

**Path parameters**

**token** `string` *required*

The receipt token to update.

**Request body**

**businessId** `string`

UUID of the owning business. Optional if the server can resolve ownership from the token, but recommended for explicit authorization.

**revoke** `boolean`

Set to `true` to permanently revoke public access. **Irreversible.** Revoking a receipt records an audit log entry and disables the public `/r/{token}` URL immediately.

**showBusinessName** `boolean`

Control whether `businessName` appears in the public receipt view.

**showVendorName** `boolean`

Control whether `vendorName` appears in the public receipt view.

**Example request — revoke a receipt**

```bash theme={null}
curl -X PATCH https://tavryn.network/api/receipts/a1b2c3d4e5f67890... \
  -H "Content-Type: application/json" \
  -d '{ "revoke": true, "businessId": "biz-uuid" }'
```

**Example response**

```json theme={null}
{
  "message": "Receipt revoked successfully. Public access disabled.",
  "revoked": true
}
```

***

## Public Receipt URL

Every receipt is accessible at a shareable URL with no authentication required:

```text theme={null}
https://tavryn.network/r/{token}
```

This URL renders a full savings certificate page including the policy checklist, verification badges, and (for real transactions) a clickable ArcScan link. Share it with finance teams, auditors, or include it in vendor communication as proof of settlement.

> [!NOTE]
>
> The public receipt URL intentionally returns the same `404` page for both nonexistent and revoked tokens. This prevents a third party from determining whether a receipt was revoked or simply never existed.


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