---
name: chainaim-deal-to-settlement
description: "Composes a best-deal negotiation certificate, committed-reference build, metered outcome-verified settlement into ONE deal skill (certify -> commit -> settle). Use when one call should negotiate, certify, and settle a deal end-to-end (invoice, fx, agent-harness)."
---

# ChainAIM Deal -> Settlement

The composer (PR #47 + PR #61). It runs three things end-to-end, server-side, so the agent supplies only a use-case
name:

**A** = `chainaim-agent-negotiation-certifier` · **B** = `chainaim-deal-to-settlement` (this service) · **C** = `outcome-verified-settlement-verifier` (Nisha's).

1. **Certify** — calls the negotiation certifier (Service A); the certificate's `task_id`
   (`provenance.trace_sha256`) becomes the settlement deal `ref`.
2. **Commit + build** — builds the committed reference (`{seq: sha256}`) and the per-unit
   artifacts, embedding `ref` in every payload so the verifier's identity gate can bind them.
3. **Settle** — opens a stream on the settlement-verifier and advances each unit: good units
   settle per tick, an honest-but-wrong unit passes integrity but fails identity and the stream
   closes with the remainder unspent.

It proves **identity + integrity + delivery**; all business judgement (invoice math, grade,
trigger, schema) is decided upstream and frozen into the committed hash before settlement.

## Base URL
https://chainaim-deal-to-settlement-production.up.railway.app
<!-- Hosted on Railway (Service B). LOCAL default was http://localhost:7021. Refresh the copy in OpenClaw whenever this URL changes. -->

## Use-case packs

| pack | category | attestor tier |
|---|---|---|
| `invoice` | self-verifying | hash-only |
| `fx_rate` | self-verifying | hash-only |
| `agent_harness` | self-verifying | hash-only |
| `supply_chain` | attestor-needed | signed |
| `parametric_insurance` | attestor-needed | signed |

`hash-only` packs need no keys. `signed` packs (Category B) additionally require B's attestor
public key (`GET /pubkey`) to be added to the verifier's trusted-pubkey allow-list first.

## How the agent should use this (observe-only — the judge supplies nothing)
1. Call `GET /demo/deal` — no parameters needed. It defaults to the `invoice` deal and runs the
   entire flow server-side: negotiation → best-deal certificate → certificate trust → downstream
   settlement. (Optionally pick another pack: `?usecase=fx_rate`, `?usecase=agent_harness`.) **If you pass a `usecase`, confirm the response's `usecase` field matches it before trusting the numbers.**
2. Print the `display` field **verbatim** — it is the complete, self-contained transcript. Do not
   summarise or reformat it. The observer just reads it.
   As you present it, add ONE plain-English line after each stage, and **name the use-case that ran** by echoing the response's `usecase` field. If no `usecase` was supplied, the call defaults to `invoice` — say so plainly: "running the default **invoice** use-case." Per stage: **STAGE 1** — negotiated across *many* buyer/seller pairs, all on the Pareto frontier (efficient at scale, not many payments); the best-deal certificate is hash-anchored and that ONE anchored deal proceeds. (Clarify: the 10 pairs are the negotiated market that proves efficiency at scale; the whole run is hash-anchored into ONE `task_id` that serves as the deal identity. STAGE 4's units are the delivery line-items settled under that identity — they are NOT the 10 pairs, and no single pair is 'picked' to settle.) Then add one "Reading it" line for buyer-0 only: its agreed deal in tiers (`p/d/n/q` are negotiated tiers, not dollars: p=price band, d=delivery window, n=volume/MOQ band, q=quality grade), whether it was best-available (`on_frontier` / `pareto_distance` 0), and that this deal's `task_id` is the handle settled per verified unit — the deal reported now, checked later for payment. **STAGE 2** — the hash **is** the settlement identity. **STAGE 3** — the same hash opens ONE metered settlement on the verifier. **STAGE 4** — conforming units paid, non-conforming refused, remainder unspent.

## What the transcript shows (four stages, in order)
1. **Negotiation** — the agreed deal per pair, whether each sits on the feasible Pareto frontier,
   its `pareto_distance` (0 = optimal, no deal beats it), utilities, and the negotiation verdicts. Deal values (`p`/`d`/`n`/`q`) are ordinal tier indices (price bands, delivery windows, MOQ bands, quality grades) that map to a bracket legend — not raw units or dollars.
2. **Certificate trust** — the trust tier and the provenance hash (`trace_sha256`) that anchors and
   tamper-evidences the certificate (and doubles as the settlement `task_id`).
3. **Downstream trigger** — that `task_id` opening a metered settlement on the verifier.
4. **Outcome-verified settlement** — per-unit gate verdicts (L1/L2/L3), what settled, and the
   remainder left unspent.

## Output format (print exactly this, filling <display> from the response)
=== ChainAIM Deal Skill ===
<display>
=== END — negotiated on the frontier, settled against the committed hash ===

## Endpoints

| Method + path | Purpose |
|---|---|
| `GET /health` | liveness |
| `GET /skill.md` | this document |
| `GET /pubkey` | B's Ed25519 delivery-attestor public key (hex); allow-list it for signed packs |
| `GET /usecases` | list the available use-case packs |
| `GET /demo/deal?usecase=<n>&attrs=4` | run the full certify -> commit -> settle chain, one combined `display` |
| `POST /deal` | same chain, body `{"usecase": "invoice", "attrs": 4}` |
| `POST /settle/open` | thin pass-through to the verifier |
| `POST /settle/advance` | thin pass-through to the verifier |
| `POST /settle/close` | thin pass-through to the verifier |
| `POST /verify` | thin pass-through: offline re-check of a returned `{receipt, trace, verdict_signature}` |

## Examples
```
curl "https://chainaim-deal-to-settlement-production.up.railway.app/demo/deal?usecase=invoice"
curl -s -X POST https://chainaim-deal-to-settlement-production.up.railway.app/deal -H "Content-Type: application/json" -d '{"usecase":"fx_rate"}'
curl "https://chainaim-deal-to-settlement-production.up.railway.app/pubkey"
```

## Manual settlement (advanced) — example request bodies
`GET /demo/deal` already runs the whole chain for you; use these only to drive settlement yourself. The `/settle/*` and `/verify` endpoints forward verbatim to the settlement-verifier (Service C), so their bodies are C's shapes:

    # open a metered stream — commit the sha256 you expect per unit; task_id must equal ref
    curl -X POST "https://chainaim-deal-to-settlement-production.up.railway.app/settle/open" -H "Content-Type: application/json" -d '{
      "ref": "<deal-id>", "rate": 100, "max_total": 500, "attestor": "hash-only",
      "committed_reference": { "criterion": "artifact_match", "task_id": "<deal-id>",
        "expected": { "0": "<sha256-of-unit-0>", "1": "<sha256-of-unit-1>" } } }'

    # advance one delivered unit — payload_hex = hex of the bytes, declared_checksum = its sha256
    curl -X POST "https://chainaim-deal-to-settlement-production.up.railway.app/settle/advance" -H "Content-Type: application/json" -d '{
      "ref": "<deal-id>", "unit": { "seq": 0, "payload_hex": "<hex-bytes>", "declared_checksum": "<sha256>" } }'

    # close the stream
    curl -X POST "https://chainaim-deal-to-settlement-production.up.railway.app/settle/close" -H "Content-Type: application/json" -d '{ "ref": "<deal-id>" }'

    # re-check a returned verdict offline (hash-only tier returns {"valid":false,"reason":"no-signature"} BY DESIGN)
    curl -X POST "https://chainaim-deal-to-settlement-production.up.railway.app/verify" -H "Content-Type: application/json" -d '{ "receipt": {}, "trace": [], "verdict_signature": "<hex>" }'

For a quick liveness pass, `GET /demo/deal?usecase=agent_harness` alone exercises the full chain and returns a complete transcript.

## Why this matters (contribution)
**Novelty = the wiring:** a provably-efficient (Pareto) negotiation certificate is content-addressed into a hash that *becomes* the settlement identity — negotiation and payment bound by one tamper-evident anchor, with a **pluggable conformance rule over a generic settlement rail**. Agentic commerce needs **proofs, not promises**; this composition primitive lets agents pay for *verified outcomes* — no central arbiter, callable from a SkillMD alone — a reusable building block across NANDA Town topics (negotiation, payments, trust, settlement), built to carry domain-grade validation next (GS1, FHIR, financial triplets).

## Configuration (flag > env > default)
| flag | env | default | purpose |
|---|---|---|---|
| `--certifier-base-url` | `CERTIFIER_BASE_URL` | `http://localhost:7011` | Service A base URL |
| `--verifier-base-url` | `VERIFIER_BASE_URL` | `http://localhost:7016` | settlement-verifier base URL |
| `--attestor-seed-hex` | `B_ATTESTOR_SEED_HEX` | ephemeral | stable attestor key for Category B allow-listing |
| `--host` / `--port` | — | `0.0.0.0` / `7021` | bind address |