Settlement
Phase 3. The buyer agent pays the settlement contract directly and the payment divides in the same transaction — operational amount, escrow contribution, scheme fee. Nothing holds the money in between, including Nustro.
This phase has two participants: the buyer agent and an on-chain contract. Your platform is not in the path, and neither is the Operator — it reads the result afterwards rather than routing the funds. That is what makes the system non-custodial rather than merely well-behaved.
The split
One call, one transaction, three destinations. All transfers succeed or the whole thing reverts.
pay(token, amount, sellerIdHash, buyerIdHash)
// emits Settled(txHash, seller, amounts…)| Leg | Goes to | When it applies |
|---|---|---|
| Operational | The seller agent’s operational wallet — keys held by its principal | Always. This is the seller’s revenue. |
| Escrow contribution | The seller agent’s escrow wallet — Operator-custodied, segregated per agent | Only while the escrow balance is below its threshold. Above it, this leg is absent. |
| Scheme fee | The scheme — Nustro’s share, and the demand and supply shares for the platforms on each side | Always, once per settled transaction, out of the seller’s proceeds — the buyer pays only the price. Visible on-chain like every other leg. |
The split ratios come from the on-chain settlement configuration registered when the seller’s market was set up. Neither agent proposes them, neither can alter them mid-transaction, and the 402 never disclosed them — the contract applies what was configured.
A worked example
A $120.00 USDC settlement for a seller still building coverage, at the recommended 5% funding rate, with a dispute window and no step-up approval:
| Amount | Destination | |
|---|---|---|
| Settled | $120.00 | Paid by the buyer agent to the contract — the price, and nothing more |
| → Operational | $113.05 | Seller’s operational wallet |
| → Escrow | $6.00 | Seller’s escrow — while below threshold |
| → Scheme fee | $0.95 | Nustro 0.40% + $0.05 = $0.53 · demand share $0.15 + 0.10% recourse = $0.27 · supply share $0.15 |
The recourse part of the demand share is zero on a final sale, and a settlement under $5 pays a flat 0.60% instead. Refunds, disputes, escrow movements and sandbox carry no fee.
Once that seller’s escrow reaches its threshold, the same transaction settles without the escrow leg and the operational amount rises accordingly. Escrow contributions are a ramp, not a permanent deduction.
What your platform sees
You are not in the path, but the outcome is fully observable — and more verifiable than an invoice, because the record is on-chain rather than in Nustro’s database.
| Source | Gives you |
|---|---|
transaction.settled webhook | Near-real-time notification, with principal_id and agent_did for routing |
GET /v1/agents/{did}/transactions | The settlement record per agent, for reconciliation |
| The chain itself | Independent confirmation of every leg — you can audit the scheme fee against the transaction without asking Nustro |
Show principals the transaction hash and link it out to the network explorer. It costs one field and it converts “trust our numbers” into “check them” — which is the entire pitch of the system your platform is built on.
Confirmation and timing
| Stage | Meaning |
|---|---|
| Submitted | The buyer agent broadcast the payment. Nothing is settled yet. |
| Confirmed | The transaction is included and the Settled event is emitted. This is the point the payment exists. |
| Verified | The Operator has read the event during facilitation — see Performance confirmation. Escrow is credited and the task opens here, not before. |
A confirmed payment is not a completed transaction. Delivery is gated on facilitation, which happens after settlement is read from the chain — a seller agent that delivers on a claimed transaction hash without facilitating carries the loss itself.
When settlement fails
Failures here are chain-level, not API-level, which changes how you handle them.
| Failure | What happens | What to surface |
|---|---|---|
| Insufficient balance | The transaction reverts. No funds move, no legs are paid. | The buyer agent’s wallet needs funding — a principal action, not a platform one. |
| Wrong network | The payment lands somewhere with no settlement contract expecting it. | This is a discovery filtering gap. Catch it before negotiation. |
| Intent expired | Facilitation refuses the settlement even though the payment confirmed. | The buyer agent must renegotiate. Funds that moved against an expired intent are a principal-to-principal matter — Nustro cannot reverse them. |
| Under- or overpayment | The amount does not match the intent; facilitation refuses. | Same as above. Pay the exact intent amount. |
The funds are already in the seller’s operational wallet, whose keys belong to its principal. Money goes back to the buyer one of two ways: the seller refunds it, or the buyer disputes it and is paid from escrow. Build your buyer-side flows so a payment is only broadcast against a fresh, valid intent.
Refunds
A refund is the seller agent paying the buyer back — all or part of a settled payment — from its own operational wallet, on its own initiative. Nustro does not move the money: the seller agent sends the transfer on-chain, then reports it, signing the call itself.
curl -X POST https://api.nustro.com/v1/refunds \
-H "AEAP-Certificate: eyJhbGciOiJFUzI1NiIsImtpZCI6…" \
-H "AEAP-Proof: MEUCIQD…" \
-H "AEAP-Timestamp: 1792591331" \
-d '{
"intent_id": "pin_6b21f9c4",
"seller_did": "did:aeap:d2146ca7-fbbd-4167-b725-b5ca2ebbb6da",
"amount": {
"amount": 40,
"currency": "USDC"
},
"tx_hash": "0x5c0e…",
"network": "arc-testnet",
"reason": "Partial delivery"
}'| Rule | Behaviour |
|---|---|
| Checked on-chain first | Nustro reads the transfer — from the seller’s operational wallet to the original buyer’s paying wallet, in the right token and amount, final — before it records anything. A transfer it cannot read yet, or that does not match, returns 402 and records nothing; retry once it is final. |
| Capped at the original | Refunds, plus anything paid to the buyer from escrow through a dispute on the same payment, never exceed the original value — 409 refund_exceeds_original. |
| Not while disputed | While a dispute on the payment is open, it cannot be refunded — 409 dispute_open. The seller resolves the claim inside the dispute instead. |
| Seller only | Only the original seller agent can report it, with its own certificate — 403 not_original_seller. A platform key or dashboard session gets 401. |
| Outside spend scope | A refund is authorized by the sale, not by a purchase: it consumes no spending limit, skips counterparty floors, and is allowed while the seller is SUSPENDED. |
Idempotent on tx_hash | Reporting the same transfer again returns the existing refund with 200. |
A recorded refund adjusts the original transaction rather than creating a new one:
its net value drops, which lowers its weight in both agents’ ratings and in the
seller’s escrow threshold. It is not a dispute and never counts against the
seller’s dispute record. A later dispute can claim only the unrefunded value.
Refunds carry no fee, and the original scheme fee is not returned. Your platform
sees each one as a refund.recorded webhook and in GET /v1/agents/{did}/refunds.
Networks and tokens
Settlement is per market: a jurisdiction, a network, and a token. A seller configured for one market cannot settle in another, and the market is derived from the buyer’s principal country.
| Property | Behaviour |
|---|---|
| Network | Chosen per market at configuration. Independent of environment — a production agent may settle on a testnet. |
| Token | A stablecoin on that network. Amounts are quoted and settled in it. |
| Contract | One settlement contract per network, registered when the market is configured. |
| Escrow | Per agent per network. It does not move between networks or environments. |