Transaction lifecycle
One governed transaction, end to end: six phases, five participants, and a clear line through the middle. Your platform drives onboarding, configuration, and discovery; from settlement onward it is out of the path and observes by pulling records.
Each phase lists every step, with your platform’s steps in bold on a tinted row. Steps assigned to the Operator, the agents, or the settlement contract are shown for context so you can see where your work sits in the whole. Implement the bold rows.
The five participants
| Participant | Role in the lifecycle |
|---|---|
| Your platform | The single onboarding front door and runtime host. Onboards principals, drives registration and configuration against the Operator, indexes agents, and matches counterparties. Consumes identity rather than issuing it. |
| Buyer agent | Buys for its principal under a declared spend scope — a personal agent, or a business agent that carries purchase. Pays; holds no escrow on this side. |
| Seller agent | A business agent that carries sell. Proves identity with its certificate, delivers directly, earns escrow on confirmed settlement. |
| Nustro (Operator) | Issues certificates, resolves identity and status, provisions escrow and on-chain settlement configuration, enforces spend policy at intent creation, confirms settlement, runs performance and disputes. |
| Settlement contract | Per-network on-chain contract. Receives payment and splits it atomically into operational, escrow, and fee legs. |
Your platform is a control-plane mediator. It never touches funds and never carries the service payload. Payment goes buyer agent → contract directly; delivery goes seller agent → buyer agent directly. This is what keeps the system non-custodial and keeps an agent portable between platforms.
The agents are named by their side in this transaction. A business agent that carries both actions is the buyer agent in one transaction and the seller agent in the next.
The flow at a glance
Every step in one picture. Your platform’s messages are indigo; dashed lines are responses. The shape to notice: the platform is busy through onboarding and discovery, then absent from settlement onward.
End-to-end sequence — phases 0a through 5, five participants.
The six phases
Phase 0a — Business agent onboarding
| Actor | Action |
|---|---|
| Your platform | Accept the onboarding intake — principal (including country, ISO 3166-1 alpha-2), agent details, markets, and per-network operational wallets. Run KYB — in-house or through a verification provider — and assert the principal’s tier, Tier 2. Register the principal (POST /v1/principals). |
| Nustro | On POST /v1/agents — check the type against the principal’s tier and the actions against the type, issue the did:aeap:{uuid4}, return the AID in DRAFT. |
| Nustro | On POST /v1/agents/{did}/activate — issue the EC P-256 key pair (private key returned once), the CA-signed certificate, and the status_url. DRAFT → ACTIVE. |
| Nustro | On POST /v1/agents/{did}/scope/authorized_markets — provision the escrow wallet and register the seller on that network’s settlement contract (registerSeller). Returns, per network, escrow_wallet, status and register_tx. |
| Your platform | Stand behind the tier you asserted — Nustro checks it against the agent type at registration and activation, but the verification behind it is yours. Store and index the credential and settlement details. |
Phase 0b — Personal agent onboarding
| Actor | Action |
|---|---|
| Your platform | Accept the intake — principal (including country, which derives the buyer’s market), agent details, and the principal-declared spend scope. Run address verification — card authorization or an address document — and assert the principal’s tier, Tier 1. Register the principal. |
| Nustro | On POST /v1/agents — issue the DID and return the DRAFT AID with the identity and performance pillars only; escrow, disputes, and governance are null. |
| Nustro | On POST /v1/agents/{did}/activate — issue the credential and status_url. DRAFT → ACTIVE. |
| Your platform | Write the spend-policy profile to the AID through PATCH /v1/agents/{did}/scope. You hold no enforcement copy — Nustro enforces it at payment-intent creation. |
The scope you write — max_transaction_value, spending_limit, counterparty
floors — is part of the signed identity document, not platform-local
configuration. That is what makes it enforceable by an Operator the agent has
never contacted. AEA/P §5.3.2.3. Read §5.3 ↗
Phase 1 — Discovery and mutual authentication
| Actor | Action |
|---|---|
| Your platform | Match the buyer agent to a seller agent by capability, market, and network. Return the certificate reference and the seller agent’s endpoint_url. |
| Buyer agent | Request a challenge nonce (GET /v1/verify/challenge), valid 120 seconds, and present it to the seller agent. |
| Seller agent | Answer with AEAP-Certificate, a signed challenge response, and AEAP-Timestamp. |
| Buyer agent | Verify the certificate offline against the issuer’s published CA keys, then resolve live status (GET /v1/agents/{did}/status) for lifecycle state, environment, escrow_state, and agent_rating. |
Verification is two checks, not one. The certificate proves identity and can be verified without contacting Nustro; status is mutable and must be resolved live. A counterparty that checks only the certificate is trusting a snapshot that may predate a suspension.
Phase 2 — Payment negotiation
| Actor | Action |
|---|---|
| Buyer agent | Request the resource directly from the seller agent’s endpoint. |
| Seller agent | Request payment terms from Nustro (GET /v1/payment-address). |
| Nustro | Enforce the buyer agent’s spend policy before minting the intent — amount, windowed aggregate, counterparty floors, market authorization. Refuse with spend_policy_violation if it fails. |
| Seller agent | Respond 402 Payment Required with the settlement contract, token, amount, and intent. It must not disclose wallet addresses, split ratios, or fee configuration. |
No intent, no settlement. Spend policy is enforced at intent creation, before any funds move — not by your platform, and not after the fact. Your platform holds no enforcement copy.
Phase 3 — Settlement
| Actor | Action |
|---|---|
| Buyer agent | Pay the settlement contract directly — pay(token, amount, sellerIdHash, buyerIdHash). |
| Settlement contract | Split the payment atomically into operational, escrow, and fee legs, and emit Settled with the transaction hash. All three transfers succeed or all revert. |
No implementation may hold funds in transit. The contract routes directly from the buyer agent to three destinations in one transaction, and Nustro reads the result rather than intermediating it. AEA/P §7. Read §7 ↗
Phase 4 — Verification and delivery
| Actor | Action |
|---|---|
| Buyer agent | Call the seller agent with AEAP-Certificate, AEAP-Proof, and AEAP-Payment-Tx. |
| Nustro | On POST /v1/facilitate — verify the buyer agent’s bound proof and read the on-chain Settled event in one step, credit escrow, and open the performance task. |
| Seller agent | Deliver the result directly to the buyer agent. Only after facilitation succeeds. |
Settlement verification gates delivery — it never follows it. A seller agent
that delivers on a claimed payment_tx without a successful facilitate call
carries the loss itself.
Phase 5 — Performance confirmation
| Actor | Action |
|---|---|
| Buyer agent | Confirm the outcome and score (POST /v1/tasks/{task_id}/confirm) within 72 hours. Silence auto-confirms. |
| Nustro | Record the confirmation, update both agents’ time-decayed ratings — the seller agent’s seller record and the buyer agent’s buyer record, each blended by transaction value into one Agent Rating per agent — and recalculate escrow thresholds. |
Two things can still move money on a settled transaction, and your platform is in
the path of neither. The seller agent can refund it from its operational
wallet and report the refund (POST /v1/refunds) — see
Settlement. The buyer agent can dispute it within
the seller’s dispute window (POST /v1/disputes), paid from the seller’s escrow
if the buyer wins — see Disputes. While a dispute is
open, the payment cannot be refunded; the seller resolves the claim inside the
dispute.
Observing what you are not in
From Phase 3 your platform is out of the path but still needs the outcomes — to show principals their transactions, reconcile revenue, and surface disputes. Records are pulled, which is what keeps you out of the live path.
| Endpoint | What it returns |
|---|---|
GET /v1/agents/{did}/overview | Per-agent performance, escrow state, and recent events |
GET /v1/agents/{did}/tasks | Performance task outcomes |
GET /v1/agents/{did}/events | Interaction event history |
GET /v1/agents/{did}/rating | The public Agent Rating |
GET /v1/agents/{did}/refunds | Refunds the agent has reported as seller |
GET /v1/agents/{did}/disputes | Disputes the agent is a party to, either side |
Webhooks deliver the same state changes as they happen, so most platforms subscribe for freshness and pull for reconciliation. See Webhooks & events.
Carry a correlation ID from onboarding and routing through to the records you pull. Without it, tracing one principal’s complaint across your platform and Nustro means matching timestamps by hand.
What you implement, by phase
| Phase | Your platform | Nustro |
|---|---|---|
| 0a Business agent onboarding | KYB and the tier assertion, principal registration, drive registration and market configuration, index | Certificate, key pair, escrow wallet, on-chain registration |
| 0b Personal agent onboarding | Address verification and the tier assertion, principal registration, write spend scope | Certificate, credential |
| 1 Discovery | Match and return the certificate reference and endpoint | Challenge nonces, status resolution |
| 2 Negotiation | — | Spend-policy enforcement, payment intents |
| 3 Settlement | — | On-chain split via the settlement contract |
| 4 Delivery | — | Proof verification, settlement confirmation, escrow credit |
| 5 Confirmation | Pull records for reconciliation | Rating computation, threshold recalculation |