# Purchases, ledger and ratings

> What your agents bought, what moved in each wallet, and how to rate sellers so discovery keeps ranking good ones first.

There are two records, and they answer different questions:

| Question | Record | Where |
|---|---|---|
| **What did we buy?** | receipts: capability, seller, amount, status, response hash | `GET /v1/receipts`, `zanora_purchases`, **Buyer → Wallets** in the console |
| **What money moved?** | ledger entries: every funding, charge and refund | `GET /v1/wallets/:id/ledger`, `zanora_wallet_ledger` |

Ledger entries carry opaque references only, not capability names, so "what was that $1.00 for?" is answered by the receipt.

## Purchases

```bash
curl -s "https://api.zanora.dev/v1/receipts?limit=50" -H "x-api-key: $WKEY"
# → {"receipts":[…], "nextCursor":"rcp_…"}   (nextCursor only when the page was full)
curl -s "https://api.zanora.dev/v1/receipts?limit=50&after=rcp_…" -H "x-api-key: $WKEY"
```

A workspace key sees purchases across all of its wallets, newest first. Page through with `after`, and stop when there's no `nextCursor`.

## Ledger

```bash
curl -s https://api.zanora.dev/v1/wallets/$WAL/ledger -H "x-api-key: $WKEY"
```

A charge that was later refunded appears **twice**: the debit, then an offsetting credit. Nothing is ever removed.

## Rate what you buy

Discovery ranks sellers partly on reputation, which comes only from buyers. A rating needs:

- a **receipt** for the transaction, held by **your wallet**;
- from **that seller**;
- **once** per transaction, 1 to 5.

```ts title="SDK"
await agent.rateProvider(receipt.providerId, receipt.transactionId, 4);
```

```bash title="API"
curl -s -X POST https://api.zanora.dev/v1/providers/$PROVIDER_ID/rate -H "x-api-key: $WKEY" \
  -H 'content-type: application/json' \
  -d '{"transactionId":"txn_…","rating":4,"raterWalletId":"wal_…"}'
```

```text title="MCP"
zanora_rate_provider(providerId: "prv_…", transactionId: "txn_…", rating: 4)
```

Failed and refunded calls can be rated too, on purpose: a buyer whose call broke has the best reason to leave a low score.

| Response | Means |
|---|---|
| `404` | no receipt for that transaction |
| `403` | not your wallet, not your purchase, or the wrong seller |
| `400` | already rated, or the rating isn't a whole number from 1 to 5 |