# Compare commerce evidence for two products with Powder Evidence

Powder Evidence compares two products in one request: name both in `query`, and the response returns `comparison_subjects`, one entry per product with its own evidence, coverage, provenance, limitations and Evidence Score. Send it as `POST https://agents.dubbleblack.com/zcj/satrhdba4ujm/api/agent/evidence`, priced at $0.10, pay the 402 price quote and retry. Powder names no winner and computes no combined score, so you set the two entries side by side and decide.

## At a glance

- **Endpoint:** `POST https://agents.dubbleblack.com/zcj/satrhdba4ujm/api/agent/evidence`, one comparison per request
- **Body:** `query` naming exactly two subjects, up to 2000 characters. Optional fields are `limit` (1 to 10, default 5) and `max_external_sources` (0 to 10, default 2).
- **Price:** $0.10. One request covers both subjects.
- **Payment:** a 402 quote paid over x402 (USDC on Base) or MPP (USDC on Tempo), then the same request retried. Pay-as-you-go needs no account and no API key.
- **Response:** JSON with `comparison_subjects`, one entry per subject. Each entry carries `subject`, `evidence`, `coverage`, `provenance`, `limitations` and `evidence_score`.
- **Limits:** two subjects at most. A request with more than two subjects returns `400`, and so does an ambiguous request with several selectors.
- **Full purchase flow:** [the buyer skill](https://agents.dubbleblack.com/zcj/satrhdba4ujm/SKILL.md)

## Write the comparison query

A comparison is a text question that names both products. Every other selector takes one item only.

| You want | Send |
| --- | --- |
| Evidence for two named products | Both names in one `query`, such as `"Compare <product A> and <product B> for my dog"` |
| Evidence for three or more products | One request per product, each `query` naming one subject. Three products cost $0.30. |
| A product by identifier | `skus`, `gtins` or `product_ids` with one item, or one `brand`, in a single-subject request |
| Fewer evidence records | `limit`, from 1 to 10 |

The endpoint rejects `budget_min`, `budget_max` and `include_insufficient_evidence`. It also rejects any field that the API reference does not list.

## Run the comparison

1. Send the request without payment:

   ```bash
   curl -sS -X POST https://agents.dubbleblack.com/zcj/satrhdba4ujm/api/agent/evidence \
     -H 'Content-Type: application/json' \
     -d '{"query": "Compare Calm CBD Soft Chews and Calm CBD Oil for my dog", "limit": 3, "max_external_sources": 0}'
   ```

   The storefront answers `402` with the price quote.

2. Pay the quote with an x402 or MPP client and resend the identical request. [The buyer skill](https://agents.dubbleblack.com/zcj/satrhdba4ujm/SKILL.md) has the steps. The example request above paid $0.10.

3. Read the `200` response. It is a JSON object with `schema_version`, `generated_at`, `evidence_available`, `evidence`, `coverage`, `provenance`, `evidence_score`, `limitations` and `comparison_subjects`, and `comparison_subjects` holds two entries, one per subject. Each entry has this shape, with types in place of values:

   ```json
   {
     "subject": "<string>",
     "evidence_available": "<boolean>",
     "evidence": ["<evidence record>"],
     "coverage": {"state": "<string>", "gap_reason": "<string>"},
     "provenance": ["<provenance record>"],
     "limitations": ["<string>"],
     "evidence_score": {"score": "<number>", "band": "<string>", "summary": "<string>", "components": {}, "formula": "<string>", "limitations": ["<string>"], "version": "<string>", "calibration_status": "<string>"},
     "results_returned": "<number>",
     "evidence_depth": "<number>"
   }
   ```

   The example comparison took 8.9 seconds.

## Read the two subject entries

Read each entry on its own terms, then compare the entries yourself.

| Field | What it tells you |
| --- | --- |
| `subject` | The subject Powder read from your query |
| `coverage.state` | That subject's coverage state: owned, supplemented, external or gap |
| `evidence` and `provenance` | That subject's evidence records and where each one comes from |
| `limitations` | What that subject's evidence does not establish |
| `evidence_score` | A bounded score from 0 to 100, with its `band`, `components` and `formula` |

Owned means Powder holds the relevant evidence and returns it. Supplemented means the evidence comes at a broader or additional granularity. Gap means Powder found no relevant owned evidence; it is a successful response, and it is not negative evidence about the product.

The Evidence Score measures how strong and deep the evidence is. It does not measure product quality, recommendation confidence or purchase probability. For a comparison, use the score inside each entry. The top-level `evidence_score` can be `null`.

## What is charged and what is not

- Each request that you pay is one charge at $0.10, whether it names one subject or two.
- Card pays a pay-as-you-go call only when the call costs $0.50 or more. For smaller calls, pay on x402 or MPP, or draw on prepaid Credits.
- Credits are optional. You buy them with `POST https://agents.dubbleblack.com/zcj/satrhdba4ujm/plans/{planId}/purchase`, using the plan id listed in [the catalog](https://agents.dubbleblack.com/zcj/satrhdba4ujm/manifest.json). A purchase needs a buyer identity and has a minimum of $0.50, or $0.50 by card.
- Powder returns evidence. It does not recommend either product.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `402` | The price quote | Pay it and retry the same request, or stop |
| `400` | Invalid body, a rejected legacy field, more than two subjects, or an ambiguous multi-selector request | Fix the body, or ask again one subject at a time |
| `settlement_failed` | Your signed payment did not settle | Fix the wallet, then send the request again for a fresh 402 |
| `429` | Rate limit exceeded | Wait for `retry_after` or `Retry-After`, then retry |
| `500` | The evidence service failed closed | Check whether the call was charged before you retry |

## Frequently asked questions

### Can Powder Evidence compare more than two products?

No. A request that names more than two subjects returns `400`. Send one request per product instead, each priced at $0.10, and set the results side by side.

### Does Powder say which of the two products is better?

No. Each entry in `comparison_subjects` stands on its own. There is no winner and no combined comparison score. The Evidence Score describes the strength and depth of each product's evidence, and the decision stays with you.

### What does it mean when one product shows a gap?

Powder found no relevant owned evidence for that subject. The response is still a successful one, and a gap says nothing negative about the product. The other entry in `comparison_subjects` is unaffected.

### Can I pay for one comparison by card?

Card pays a pay-as-you-go call only when the call costs $0.50 or more. Below that amount, pay over x402 or MPP, or buy Credits by card from $0.50, which needs a buyer identity.

### How much does a product comparison cost?

One comparison is one request at $0.10, and that one request covers both products. The 402 states the exact amount before you pay.

## Keep reading

- [Buyer skill](https://agents.dubbleblack.com/zcj/satrhdba4ujm/SKILL.md): the full purchase flow
- [Error reference](https://agents.dubbleblack.com/zcj/satrhdba4ujm/errors.md): every code and how to respond
- [Powder Evidence API reference](https://agents.dubbleblack.com/zcj/satrhdba4ujm/services/powder-evidence/openapi.json): request fields and the response schema

---

Updated 2026-10-20. All DubbleBlack guides: https://agents.dubbleblack.com/guides.md. Storefront: https://agents.dubbleblack.com/zcj/satrhdba4ujm/llms.txt.