xytara

xytara is the machine transaction and execution layer for the final two-repo public stack.

It exists to let agents, developers, and systems:

• discover tasks and workflows
• quote work before execution
• pay through supported payment paths
• execute tasks and workflows
• receive deliverables
• inspect lifecycle state
• operate through summaries and dashboards
• integrate third-party adapters
• emit proof-compatible facts for xoonya verification

This repo is the hot-state commerce layer. It does not define base proof semantics. It references and emits proof-compatible facts, while xoonya owns canonical proof.

Start Here

If you are new to the public stack, use this order:

1. read START_HERE.md
2. run node examples/quickstart.js
3. run npm run verify:all
4. use FINAL_CONTRACT.md and SERVICE_CONTRACT.md as the durable public contract

If you are building adapters, continue with:

• adapters/AUTHORING_GUIDE.md
• adapters/ONBOARDING_POSTURE.md
• adapters/THIRD_PARTY_SUBMISSION_PROCESS.md

If you are wiring the native BSV settlement base, continue with:

• BSV_TERANODE_SETUP.md
• REAL_PAYMENT_SETUP.md

If you are wiring the first human checkout path, continue with:

• HUMAN_CHECKOUT_AND_RUNTIME_BRIDGE_PATTERN.md
• RUNTIME_BRIDGE_CONTRACT.md
• HOSTED_CHECKOUT_CONTRACT.md
• CHECKOUT_TO_CREDITS_AND_DISPATCH_PLAN.md

Production Path

The intended production-facing default path is now:

1. discover a capability
2. preview or quote the transaction path
3. spend existing credits first when the caller prefers the reusable account path
4. fall back to direct machine payment when credits are not available or not preferred
5. execute through the default machine path
6. inspect the transaction-side result and lifecycle state
7. hand the result into xoonya
8. review and run the proof-side completion path

The machine-facing execution surface now also supports a first-class reusable balance posture:

• set payment_preference: "credits_first" on POST /v1/commands/execute when the caller wants to spend existing account credits before requesting a fresh payment
• default spend posture is open_spend: if the funded caller can pay, xytara should spend and execute without extra runtime ceremony
• bounded spend posture is optional and only applies when the caller intentionally uses an agent_id and/or budget_id
• inspect account credit state with GET /v1/economics/accounts/:account_id/credit-balance
• inspect deterministic usage metering state with GET /v1/economics/accounts/:account_id/metering-summary, GET /v1/economics/accounts/:account_id/usage-meters, and GET /v1/economics/accounts/:account_id/usage-meters/:usage_meter_id
• expect reconciliation and operator-export surfaces to carry the same metering trail for audit visibility
• export a canonical cross-repo economic handoff bundle with POST /v1/economics/handoff-bundles/economic-consequence
• expect POST /v1/transaction-center/result-packages/export and result-package continuation export/prepare surfaces to auto-carry that same canonical economic bundle whenever the execution path spent credits and produced a deterministic usage meter
• inspect pack-backed entitlement pools with GET /v1/economics/accounts/:account_id/entitlements and GET /v1/economics/accounts/:account_id/entitlements/summary
• inspect low-balance and replenishment posture with GET /v1/economics/accounts/:account_id/entitlements/replenishment-summary
• inspect one pool’s replenishment view with GET /v1/economics/accounts/:account_id/entitlements/:entitlement_id/replenishment-view
• inspect effective account spend posture with GET /v1/economics/accounts/:account_id/policy-pack
• inspect effective agent spend posture with GET /v1/economics/accounts/:account_id/agents/:agent_id/policy-view
• preflight a proposed credit spend with POST /v1/economics/rails/credits/preview-spend
• record explicit bounded credit consumption with POST /v1/economics/rails/credits/consume
• issue externally verified top-up grants with POST /v1/credit-bridge/grants
• inspect externally issued grants with GET /v1/credit-bridge/grants and GET /v1/credit-bridge/grants/:grant_id
• discover reusable funding posture through GET /v1/credit-packs, GET /v1/credit-packs/summary, and GET /v1/credit-pack?ref=<pack_id>
• external grant callers can now fund a named public pack such as credits.agent, and xytara will validate and record that pack identity directly

The SDK now exposes the same posture directly for agent callers:

• client.getCreditPackSummary()
• client.getCreditBalance(accountId)
• client.previewUsageMetering({ account_id, task_ref?, workflow_ref?, units? })
• client.getUsageMeteringSummary(accountId)
• client.listUsageMeters(accountId)
• client.getUsageMeter(usageMeterId, accountId?)
• client.exportEconomicConsequenceHandoffBundle({ account_id, usage_meter_id, credit_spend_id, meter_profile_ref? })
• client.listEntitlements(accountId)
• client.getEntitlementSummary(accountId)
• client.getEntitlement(entitlementId, accountId?)
• client.getEntitlementReplenishmentSummary(accountId)
• client.getEntitlementReplenishmentView(entitlementId, accountId?)
• client.updateEntitlementReplenishmentPreference(entitlementId, payload, accountId?)
• client.previewCreditSpend({ account_id, task_ref, units, agent_id?, budget_id? })
• client.getCreditSpendPolicyPack(accountId)
• client.getAgentCreditSpendPolicyView(agentId, accountId?)
• client.executeWithCreditsFirst(payload, options?)

The runtime now also supports a bounded delegated spend path for repeat-use automation:

• issue a spend credential through POST /v1/account-auth/spend-credentials
• use that credential as authorization: Bearer <spend_credential>
• optionally bind the credential to a pack_id or entitlement_id when spend should stay inside one value pool
• execute through the same credits_first path without sharing broad operator secrets
• revoke it through POST /v1/account-auth/spend-credentials/:credential_id/revoke

SDK helpers now include:

• client.createSpendCredential(payload, { bearerToken })
• client.listSpendCredentials(filters?, { bearerToken? })
• client.getSpendCredential(credentialId, { bearerToken? })
• client.revokeSpendCredential(credentialId, payload, { bearerToken })
• client.executeWithSpendCredential(payload, { spendToken })

This keeps one-off usage and repeat usage on the same public spine:

• direct pay when the caller is using the stack once
• credit balance when the caller is already funded and wants low-friction repeat execution
• optional agent and budget controls can still bound that spend without changing the execution surface

It also keeps the human checkout boundary clean:

• an external merchant-facing system can verify a purchase and issue a bounded credit grant into xytara
• xytara records the granted value and consumes it during later runtime operations
• the runtime does not need to absorb provider-specific checkout semantics to support repeat usage
• in production, POST /v1/credit-bridge/grants should normally be protected with XYTARA_CREDIT_BRIDGE_BEARER_TOKEN

The first human-facing convenience path now follows a parallel narrow route:

1. create hosted purchase intent
2. create checkout session
3. normalize payment success
4. issue credits or entitlement
5. dispatch through the runtime bridge when needed
6. converge back into the same xytara and xoonya spine

The first direct hosted execution path now also has a public runtime bridge surface:

• POST /v1/runtime-bridge/dispatch
• GET /v1/runtime-bridge/dispatches
• GET /v1/runtime-bridge/dispatches/:request_id

The hosted payment side is intentionally asymmetric:

• pay-in should be simple and fast
• execution and delivery should follow immediately after valid payment
• refund or reversal requests should enter review first
• no autonomous payout path should exist outside explicit operator review and completion

The operator shell now also carries hosted checkout visibility so purchase, dispatch, and refund-review load can be monitored from the same public control surface.

The rest of this README explains the full surface area and milestone trail, but the public starting posture should now be understandable from that one default path.

Commerce Loop

The public product loop is:

1. discover
2. quote
3. pay
4. execute
5. deliver
6. inspect
7. prove

The package and service surfaces both follow that model.

The current built-in catalog now covers a broader first-party 1.4.0 kernel than the original narrow seed, including:

• trust and receipt validation/handoff tasks
• runtime consequence tasks
• jobs, credits, and policy tasks
• first-party a2a negotiation and commit tasks
• first-party a2c session and task-pack preview tasks
• identity attestation and registry-link tasks
• registry and anchoring tasks
• discovery, admission, and settlement tasks
• an initial built-in mcp adapter task

The current restoration phase also starts carrying grouped public workflows for:

• a2a settlement negotiation
• a2c tooling/session flow
• identity registry plus anchoring flow
• registry pack bundling plus anchoring flow

The current built-in settlement posture also now reflects the canonical first-party center of gravity across:

• ethereum_evm
• bsv_teranode
• solana
• proton_xpr
• antelope_eosio

The economic artifact posture is also now more explicit across the default machine loop:

• quotes carry normalized payment, settlement, and treasury state
• executed transactions and receipts carry the same normalized economic objects
• payment-ledger entries preserve linked payment / settlement / treasury outcomes
• the default first-party economic path is easier to inspect without provider-shaped logic

The same artifacts now also expose a normalized default_path object so the bundled economic center of gravity is visible as data instead of being inferred indirectly.

The package and service also expose a default transaction center surface so the out-of-the-box path is easier to inspect directly:

• default protocol lane: mcp
• default payment protocol: x402
• default settlement center: built-in chain settlement with bsv_teranode as the native default across the canonical bundled settlement modes
• default treasury landing posture: account treasury destination by settlement mode

That same default center is also reflected in direct helper paths for default MCP usage, so the default path can be previewed or quoted without repeating the full integration-selection story each time.

The 1.6.0 convergence line starts broadening that same default path into grouped first-party entry packs:

• default.mcp.tool.invoke
• default.a2c.tooling.run
• default.identity.anchor.run

These default packs are intended to make the public machine loop easier to consume as grouped first-party paths instead of only as low-level primitives.

The package and service now also expose:

• default transaction economics visibility
• default transaction task-pack catalog, summary, and detail routes
• direct SDK helpers for default task-pack preview, quote, and invoke

The next 1.6.0 carry also adds guided default loops on top of those packs:

• default loop catalog and detail routes
• direct loop-run service surface
• SDK helpers that return bundled result-set, linked-record, activity, and economics summaries together

That means the first-party path is easier to both run and inspect without manually stitching together monitor, receipt, delivery, and payment-ledger helpers after execution.

The current 1.7.0 line starts widening that surface into real grouped transaction classes:

• transaction-class pack catalog, summary, and detail routes
• grouped transaction-class run routes for first-party commerce classes
• proof-handoff summaries that make the next step into xoonya more obvious from transaction outputs

This is the first step beyond “clear default loop” toward “broader useful machine-commerce classes plus clearer commerce-to-proof follow-through.”

The current 1.8.0 line starts filling a thinner part of the interaction spine before committed execution:

• grouped pre-commit pack catalog, summary, and detail routes
• grouped pre-commit run routes for negotiation, admission, and commit-readiness posture
• readiness summaries that make the next committed transaction surface more explicit

This is intended to make the protocol-entry to committed-transaction transition feel more like one composable machine spine instead of a set of disconnected route families.

The same 1.8.0 line also starts exposing grouped interaction spine paths that compose:

• pre-commit readiness
• committed execution
• proof-aware handoff posture

as one clearer cross-layer machine path instead of making callers stitch the layers together manually.

The current 1.9.0 line starts hardening the output side of that spine into cleaner extension seams:

• interaction result-package catalog, summary, and detail routes
• direct result-package run surfaces derived from grouped spine paths
• seam summaries that classify execution/consequence, payment/settlement/treasury, and proof-handoff carry together
• result-package export surfaces that produce a portable handoff bundle for proof-side follow-through

This is intended to make grouped spine outputs easier to treat as stable artifacts and future adapter-ready boundaries instead of one-off route responses.

The current 1.10.0 line starts building on that by exposing reusable continuation templates on top of result packages:

• result-package continuation catalog, summary, and detail routes
• direct continuation run surfaces that preserve the default next proof path
• continuation preparation surfaces that emit proof-ready request templates
• continuation preparation summary surfaces that expose the stable prepared-artifact view directly
• continuation summaries that make the default transaction-to-proof bridge explicit instead of inferred
• prepared continuation artifacts that classify the preserved execution, economic, and proof-facing context that survives into proof-native follow-through
• extension-seam summaries that distinguish stable carry from future adapter-ready boundary points on that durable path
• reusable-default summaries that expose the stable prepared artifact as a clearer default follow-through pattern
• reusable-default template surfaces that package that same default path into a direct proof-side review request
• extension-template surfaces that turn the durable transaction-side artifact into a reusable proof-side extension-review request

This is intended to make the public stack easier to compose after grouped execution, not just easier to inspect.

The current 1.14.0 line starts hardening that reusable path into a clearer public composition contract:

• prepared-artifact composition-contract summaries
• composition-contract template surfaces for proof-side contract review
• compact composition-contract bundles for direct transaction-side contract reuse
• clearer public contract ids across the reusable-default continuation path

This is intended to make the transaction-side continuation path easier to treat as a stable public contract instead of only a strong reusable default.

The current 1.15.0 line starts turning that same contract path into a clearer adapter-ready public bridge:

• prepared-artifact bridge summaries on top of the composition-contract continuation path
• bridge template surfaces that package the next proof-side review request directly
• compact bridge bundles for direct transaction-side bridge reuse
• compact bridge-carry surfaces for direct transaction-side bridge reuse

This is intended to make the transaction-side continuation path easier to hand across a stable adapter-ready bridge instead of treating bridge preparation as an implicit follow-on concern.

The current 1.16.0 line starts turning that bridge into a clearer stable public handoff contract:

• prepared-artifact handoff summaries on top of the bridge path
• direct handoff template surfaces for proof-side handoff continuity review
• compact handoff bundles for direct transaction-side handoff reuse
• compact handoff-carry surfaces for direct transaction-side handoff reuse

This is intended to make the transaction-side continuation path easier to treat as a stable handoff contract instead of only a well-described bridge.

The current 1.17.0 line starts turning that stable handoff contract into a clearer adapter-consumable handoff surface:

• adapter-consumable handoff-surface summaries on top of prepared handoff artifacts
• direct handoff-surface template routes for proof-side intake review
• compact handoff-surface bundles for direct adapter-facing reuse
• clearer adapter-facing handoff-surface ids and stable consumable carry

This is intended to make the transaction-side continuation path easier to consume directly as a stable adapter-facing handoff surface instead of only a well-described handoff contract.

The current 1.18.0 line starts turning that adapter-consumable handoff surface into a clearer adapter-usable handoff package:

• adapter-usable handoff-package summaries on top of prepared handoff artifacts
• compact handoff-package bundles for direct adapter-facing use
• default handoff-package summaries for the next proof-side follow-through
• clearer adapter-facing handoff-package ids and stable usable carry

This is intended to make the transaction-side continuation path easier to use directly as a stable public handoff package instead of only a surface that still needs extra glue logic.

The current 1.19.0 line starts turning that adapter-usable handoff package into a clearer adapter-ready execution package:

• execution-package summaries on top of the default handoff-package path
• compact execution-package bundles for direct adapter-facing execution posture
• default execution-package summaries for the next proof-side execution run posture
• clearer execution-package ids and stable execution-ready carry

This is intended to make the transaction-side continuation path easier to execute against directly as a stable public package instead of only a package that still needs execution glue.

The current 1.20.0 line starts turning that adapter-ready execution package into a clearer adapter-operable execution contract:

• execution-contract summaries on top of the default execution-package path
• compact execution-contract bundles for direct adapter-facing operation posture
• default execution-contract summaries for the next proof-side execution-contract run posture
• clearer execution-contract ids and stable operable carry

This is intended to make the transaction-side continuation path easier to operate against repeatedly as a stable public contract instead of only a package that is execution-ready by posture.

The current 1.21.0 line starts turning that adapter-operable execution contract into a clearer adapter-stable operating contract:

• operating-contract summaries on top of the default execution-contract path
• compact operating-contract bundles for direct adapter-facing stable operation posture
• default operating-contract summaries for the next proof-side operating-contract run posture
• clearer operating-contract ids and stable recurring operating carry

This is intended to make the transaction-side continuation path easier to depend on repeatedly as a durable public operating contract instead of only a contract that is operable in the moment.

The current 1.22.0 line starts turning that adapter-stable operating contract into a clearer adapter-reliable operating interface:

• operating-interface summaries on top of the default operating-contract path
• compact operating-interface bundles for direct adapter-facing reliable interface posture
• default operating-interface summaries for the next proof-side operating-interface run posture
• clearer operating-interface ids and stable reliable interface carry

This is intended to make the transaction-side continuation path easier to rely on operationally as a durable public interface instead of only a stable operating contract shape.

The current 1.23.0 line starts turning that adapter-reliable operating interface into a clearer adapter-integrable operating path:

• operating-integration summaries on top of the default operating-interface path
• compact operating-integration bundles for direct adapter-facing integration posture
• default operating-integration summaries for the next proof-side operating-integration run posture
• clearer operating-integration ids and stable integrable carry

This is intended to make the transaction-side continuation path easier to plug into adapters directly as a durable public operating path instead of only a reliable interface shape.

The current 1.24.0 line starts turning that adapter-integrable operating path into a clearer adapter-ready default path:

• operating-path summaries on top of the default operating-integration path
• compact operating-path bundles for direct adapter-facing default-path posture
• default operating-path summaries for the next proof-side operating-path run posture
• clearer operating-path ids and stable default-path carry

This is intended to make the transaction-side continuation path easier to use as the obvious first public adapter path instead of only a path that is integrable with a little extra coordination.

The current 1.25.0 line starts turning that adapter-ready default path into a clearer adapter-complete default path:

• complete-default-path summaries on top of the default operating-path path
• compact complete-default-path bundles for direct adapter-facing complete-path posture
• default complete-default-path summaries for the next proof-side complete-default-path run posture
• clearer complete-default-path ids and stable complete-path carry

This is intended to make the transaction-side continuation path easier to adopt as the complete public default path an outside builder can use without needing private interpretation.

The current 1.26.0 line finalizes that public shape into a cleaner production-ready package:

• a publishable START_HERE.md onboarding path
• clearer top-level README entry points for the default production flow
• publishable contract and terminology docs carried in the package tarball
• naming cleanup that keeps the public story anchored to xytara and xoonya

This is intended to make the public transaction-side package feel like a finished production-facing product instead of a strong stack that still assumes milestone-history context.

Package Surface

The SDK is broad, but it stays organized into a few repeatable families instead of one-off surfaces.

The main families are:

• discovery and catalog
• schemas, templates, and validation
• quotes, previews, execution, and wait flows
• records, operations, and operator summaries
• inspection, reconciliation, and export helpers

The intended usage style is simple:

• use raw getters when you need exact records
• use summary/list helpers when you need compact high-signal state

Adapter Model

Adapter support is now a first-class public surface.

Core contract files:

• adapter-manifest.schema.json
• integration-registration-record.schema.json
• integration-certification-pack.schema.json
• integration-submission-bundle.schema.json
• integration-submission-bundle-set.schema.json
• interfaces.js

Builder-facing docs:

• AUTHORING_GUIDE.md
• THIRD_PARTY_SUBMISSION_PROCESS.md
• ONBOARDING_POSTURE.md

Reference examples:

• built-in class examples: example-execution-adapter.manifest.json, example-execution-adapter.js, example-settlement-adapter.manifest.json, example-settlement-adapter.js
• staged third-party artifact examples: protocol, identity, and settlement registration/certification/submission-bundle examples live under adapters/examples

Current adapter tooling exposes:

• ADAPTER_INTERFACE_VERSION
• validateAdapterImplementation(...)

Initial certification starts with:

npm run verify:adapters

The current seed freezes the starter contract for:

• adapter identity
• adapter class
• registration posture
• certification posture
• compatibility
• health contract
• idempotency contract
• failure contract
• proof contract

The current onboarding path is now documented for third parties:

1. choose adapter class
2. build manifest against the schema
3. implement the interface contract
4. certify locally with npm run verify:adapters
5. declare registration and certification posture
6. promote through explicit runtime registration

Third-party integrations scale through one stable pattern:

• manifest declares registration posture
• manifest declares certification posture
• certification runs locally first
• promotion produces a normalized registration record
• runtime registration remains an explicit product action
• discovery can later surface maturity and trust without changing runtime contracts

Discovery can represent non-bundled staged examples in the same normalized view:

• built-in integrations can appear as unregistered but production-default
• staged third-party integrations can appear as staging_registered
• registration state stays separate from proof and commerce semantics

The registry model now also has an explicit ingestion path:

• adapter manifest defines the adapter contract
• registration record defines promotion state
• certification pack defines submitted verification evidence
• submission bundle groups the reusable submission artifact
• registry ingestion helper normalizes the runnable integration view

The package surface also supports registry snapshot/export helpers, so multiple imported integrations can be packaged together without inventing a one-off format every time.

Submission bundles can be exported back into a bundle set and then turned into a normalized registry snapshot.

The same artifact model also produces thin review summaries:

• submission bundles can be summarized for reviewer/operator inspection
• submission bundle sets can be summarized as one staged review package
• registry snapshots can be summarized as a review-ready state report

That keeps inspection aligned with the real integration artifacts instead of inventing a parallel control-plane format.

The intended posture is:

• built-in certified integrations can be production-default
• staged third-party integrations can be discoverable and reviewable
• staged third-party integrations should normally require explicit selection
• discoverable does not mean default

The promotion-readiness layer now makes that posture explicit as review data:

• review-ready means an integration is staged and inspectable
• default-eligible means it is allowed to participate in default selection
• production-default-ready means its certification, maturity, bundled posture, and selection posture all line up
• blockers are returned as data instead of being left implicit

That distinction matters as the registry grows.

The promotion-action preview layer now builds on top of that readiness data without introducing mutation:

• action previews stay read-only
• current posture and resulting posture are both visible
• requested action validity is explicit
• blockers and blocker categories remain inspectable as data
• the preview layer explains what would change before any future control-plane work exists

There is also a small repo-local registry CLI for reviewer/operator use when working from a cloned xytara repository:

• node scripts/registry_cli.js validate-bundle --example protocol
• node scripts/registry_cli.js validate-bundle --example identity
• node scripts/registry_cli.js validate-bundle --example settlement
• node scripts/registry_cli.js export-bundle-set
• node scripts/registry_cli.js export-snapshot
• node scripts/registry_cli.js review-bundle --example protocol
• node scripts/registry_cli.js review-bundle --example identity
• node scripts/registry_cli.js review-bundle-set
• node scripts/registry_cli.js review-snapshot
• node scripts/registry_cli.js promotion-readiness --integration partner.protocol.acme_mcp
• node scripts/registry_cli.js promotion-action-preview --integration partner.protocol.acme_mcp --action complete_certification
• node scripts/registry_cli.js promotion-action-set --integration partner.protocol.acme_mcp
• node scripts/registry_cli.js promotion-action-set-summary --source third_party_example --bundled false

Integration Selection

xytara now treats integration selection as an explicit part of the commerce contract.

Callers can provide:

• integration_id
• integration_ids
• integration_context
• protocol
• payment_protocol
• settlement preferences

Selection precedence is:

1. validate explicitly requested integrations
2. resolve protocol and payment protocol hints
3. resolve task-backed execution and identity integrations
4. resolve settlement integration from the requested settlement mode
5. reject the request if an explicit integration is unknown or incompatible

This keeps the model stable as more integrations are added:

• explicit overrides must be valid
• defaults remain predictable
• defaults only come from integrations that explicitly opt into default selection
• explicit requests only constrain the relevant adapter class
• protocol and settlement translation never redefine commerce semantics

Quickstart

Run:

node examples/quickstart.js

The quickstart exercises:

• health and catalog
• discovery summaries and filters
• restored a2a, a2c, and identity catalog families
• staged-vs-default integration posture
• submission bundle-set export
• pricing, schema, and template access
• validation
• quote and execution flows
• dedicated mcp invocation flow
• named a2a negotiation and commit lanes
• named a2c session and pack-preview lanes
• named identity attestation preview and registry-link lanes
• named registry-pack bundle and anchoring-pack preview lanes
• grouped a2a, a2c, identity-anchor, and registry-pack-anchor convenience flows
• named runtime, admission, registry, and anchoring task lanes
• named trust and receipt-handoff lanes
• lifecycle and operator helpers
• service-backed client usage

Service Surface

Run:

npm start

Then in another shell:

curl http://127.0.0.1:4320/v1/catalog/summary
curl http://127.0.0.1:4320/v1/operations/dashboard
curl http://127.0.0.1:4320/v1/operations/attention-records
curl -X POST http://127.0.0.1:4320/v1/trust/handoffs/emit ^
  -H "content-type: application/json" ^
  -H "authorization: Bearer demo-api-key" ^
  -d "{\"subject_id\":\"subject-1\",\"execution_ref\":\"exec-1\"}"
curl -X POST http://127.0.0.1:4320/v1/admission/preview ^
  -H "content-type: application/json" ^
  -H "authorization: Bearer demo-api-key" ^
  -d "{\"source_zone_id\":\"zone-a\",\"target_zone_id\":\"zone-b\"}"
curl -X POST http://127.0.0.1:4320/v1/a2a/negotiate ^
  -H "content-type: application/json" ^
  -H "authorization: Bearer demo-api-key" ^
  -d "{\"counterparty_agent_id\":\"agent-counterparty-1\",\"task_pack_ref\":\"pack.a2a.demo\",\"negotiation_mode\":\"quote_then_commit\"}"
curl -X POST http://127.0.0.1:4320/v1/a2c/packs/preview ^
  -H "content-type: application/json" ^
  -H "authorization: Bearer demo-api-key" ^
  -d "{\"agent_id\":\"agent-demo\",\"pack_ref\":\"pack.tools.research\"}"
curl -X POST http://127.0.0.1:4320/v1/identity/attest/preview ^
  -H "content-type: application/json" ^
  -H "authorization: Bearer demo-api-key" ^
  -d "{\"subject_id\":\"subject-identity-1\",\"registry_scope\":\"registry.identity.default\"}"
curl -X POST http://127.0.0.1:4320/v1/registry/packs/bundle ^
  -H "content-type: application/json" ^
  -H "authorization: Bearer demo-api-key" ^
  -d "{\"pack_ref\":\"pack.registry.identity\",\"subject_ids\":[\"subject-identity-1\",\"subject-identity-2\"]}"
curl -X POST http://127.0.0.1:4320/v1/a2a/flows/settlement ^
  -H "content-type: application/json" ^
  -H "authorization: Bearer demo-api-key" ^
  -d "{\"counterparty_agent_id\":\"agent-counterparty-1\",\"task_pack_ref\":\"pack.a2a.demo\",\"negotiation_mode\":\"quote_then_commit\",\"negotiation_id\":\"negotiation-flow-1\",\"intent_id\":\"intent-a2a-flow-1\"}"
curl -X POST http://127.0.0.1:4320/v1/identity/flows/anchor ^
  -H "content-type: application/json" ^
  -H "authorization: Bearer demo-api-key" ^
  -d "{\"subject_id\":\"subject-identity-1\",\"registry_scope\":\"registry.identity.default\",\"record_type\":\"identity_attestation\",\"registry_record_id\":\"registry-record-identity-1\",\"commitment_hash\":\"commitment-identity-1\"}"
curl -X POST http://127.0.0.1:4320/v1/mcp/tools/invoke ^
  -H "content-type: application/json" ^
  -H "authorization: Bearer demo-api-key" ^
  -d "{\"tool_name\":\"zones.lookup\",\"arguments\":{\"zone_id\":\"zone-1\"}}"
curl -X POST http://127.0.0.1:4320/v1/payment-quotes ^
  -H "content-type: application/json" ^
  -d "{\"command\":\"quickstart\",\"task_ref\":\"trust.verify\",\"body\":{\"subject_id\":\"subject-1\"}}"

Environment example:

• .env.example

Production payment note:

• set XYTARA_PAYMENT_VERIFICATION_MODE=local_signed to enforce verifiable signed payment acceptance instead of plain header presence
• provide buyer wallet verification material through XYTARA_WALLET_REGISTRY_JSON or XYTARA_WALLET_REGISTRY_PATH
• set XYTARA_TREASURY_DESTINATION_ID and related treasury env vars so accepted payments land in your merchant treasury posture instead of the default local account placeholder
• built-in x402 is the admission lane; real external payout/custody still depends on the payment rail and treasury destination you configure behind that lane

Primary service routes:

• GET /health
• GET /v1/catalog
• GET /v1/catalog/summary
• GET /v1/catalog/task?ref=<task_ref_or_alias>
• GET /v1/catalog/workflows
• GET /v1/catalog/workflow?ref=<workflow_ref_or_alias>
• GET /v1/integrations
• GET /v1/integrations/summary
• GET /v1/integrations/classes
• GET /v1/integrations/protocols
• GET /v1/integrations/settlement-modes
• GET /v1/integrations/promotion-readiness
• GET /v1/integrations/:integration_id/promotion-readiness
• GET /v1/integrations/promotion-actions
• GET /v1/integrations/:integration_id/promotion-actions
• POST /v1/integrations/promotion-actions/preview
• POST /v1/integrations/review/submission-bundle
• POST /v1/integrations/review/submission-bundle-set
• POST /v1/integrations/review/registry-snapshot
• POST /v1/payment-quotes
• POST /v1/trust/handoffs/emit
• POST /v1/trust/handoffs/validate
• POST /v1/execution-receipts/handoffs/emit
• POST /v1/execution-receipts/handoffs/validate
• POST /v1/receipt-ledger/handoffs/emit
• POST /v1/receipt-ledger/handoffs/validate
• POST /v1/admission/preview
• POST /v1/a2a/negotiate
• POST /v1/a2a/commit
• POST /v1/a2a/flows/settlement
• POST /v1/a2c/sessions/open
• POST /v1/a2c/packs/preview
• POST /v1/a2c/flows/tooling
• POST /v1/identity/attest/preview
• POST /v1/identity/registry/link
• POST /v1/identity/flows/anchor
• POST /v1/runtime/emit
• POST /v1/runtime/anchor
• POST /v1/runtime/emit-anchor
• POST /v1/registry/register
• POST /v1/registry/packs/bundle
• POST /v1/registry/packs/anchor
• POST /v1/anchoring/submit
• POST /v1/anchoring/packs/preview
• GET /v1/coordination-center
• GET /v1/coordination-center/summary
• GET /v1/zones
• GET /v1/zones/compatibility-profiles
• GET /v1/zones/:zoneId/constitution
• POST /v1/coordination-center/interpretation-handoff/validate
• POST /v1/coordination-center/handshake-preview
• POST /v1/coordination-center/cross-zone-preview
• POST /v1/coordination-center/admission-case-projection
• POST /v1/coordination-center/admission-case-bundle
• POST /v1/coordination-center/operator-view
• POST /v1/coordination-center/admin-view
• POST /v1/coordination-center/admission-ops-pack
• POST /v1/coordination-center/admission-workflow-pack
• POST /v1/coordination-center/coordination-pack
• POST /v1/coordination-center/review-link
• GET /v1/coordination-center/zones-dashboard
• POST /v1/coordination-center/zones-dashboard-pack
• POST /v1/mcp/tools/invoke
• GET /v1/payment-quotes
• GET /v1/payment-quotes/:quote_id
• POST /v1/commands/execute
• POST /x402/commands/execute
• POST /x402/mcp/tools/invoke
• GET /v1/governed-transactions
• GET /v1/governed-transactions/:transaction_id
• GET /v1/receipts
• GET /v1/receipts/:receipt_id
• GET /v1/payment-ledger
• GET /v1/payment-ledger/:payment_id
• GET /v1/deliveries
• GET /v1/deliveries/:delivery_id
• GET /v1/disputes
• POST /v1/disputes
• GET /v1/disputes/:dispute_id
• POST /v1/disputes/:dispute_id/actions
• GET /v1/refunds
• POST /v1/refunds
• GET /v1/refunds/:refund_id
• POST /v1/refunds/:refund_id/actions
• POST /v1/remediation-tickets
• GET /v1/remediation-tickets
• GET /v1/remediation-tickets/:ticket_id
• POST /v1/remediation-tickets/:ticket_id/actions
• GET /v1/reconciliation-report
• GET /v1/operator-export-pack
• GET /v1/operations/dashboard
• GET /v1/operations/attention-records
• GET /v1/operator-shell
• GET /v1/operator-shell/summary
• POST /v1/operator-shell/summary
• POST /v1/operator-shell/workflow-pack
• POST /v1/operator-shell/admin-pack
• GET /v1/agent-accounts
• POST /v1/agent-accounts
• GET /v1/agent-accounts/:account_id
• POST /v1/economics/budgets
• POST /v1/economics/budgets/:budget_id/status
• POST /v1/economics/agents
• POST /v1/economics/agents/:agent_id/status
• POST /v1/economics/receipts
• POST /v1/economics/receipts/:receipt_id/lifecycle
• POST /v1/economics/receipts/:receipt_id/operator-action
• POST /v1/economics/allocations/mint
• POST /v1/economics/allocations/reverse
• POST /v1/economics/rails/credits/preview
• POST /v1/economics/rails/credits/apply
• POST /v1/economics/receipt-ledger/validate
• POST /v1/economics/interpretation-handoff
• POST /v1/economics/markets/preview
• POST /v1/economics/markets/workflow-pack
• POST /v1/economics/markets/signoff-pack
• POST /v1/economics/markets/coordination-pack
• GET /v1/economics/accounts/:account_id/budgets
• GET /v1/economics/accounts/:account_id/agents
• GET /v1/economics/accounts/:account_id/receipts
• GET /v1/economics/accounts/:account_id
• GET /v1/economics/accounts/:account_id/operator-view
• GET /v1/economics/accounts/:account_id/operator-dashboard
• GET /v1/economics/accounts/:account_id/treasury-summary
• GET /v1/economics/accounts/:account_id/ledger-export
• GET /v1/economics/accounts/:account_id/treasury-drilldown
• GET /v1/economics/accounts/:account_id/reconciliation-pack
• GET /v1/economics/accounts/:account_id/treasury-workflow-pack
• GET /v1/economics/accounts/:account_id/treasury-signoff-pack
• GET /v1/economics/accounts/:account_id/policy-summary
• GET /v1/economics/accounts/:account_id/rail-summary
• GET /v1/economics/accounts/:account_id/rail-workflow-pack
• GET /v1/economics/accounts/:account_id/rail-signoff-pack
• POST /v1/economics/jobs/:job_id/operator-action
• GET /v1/economics/evidence/receipts/:receipt_ref
• GET /v1/economics/evidence/jobs/:job_id
• GET /v1/economics/integration/jobs/:job_id

The Wave C coordination carry-over line adds a bounded coordination center on top of the public transaction spine:

• zone discovery, compatibility profiles, and constitution lookup
• interpretation-handoff validation and cross-zone handshake preview
• cross-zone admission-case projection and portable case-bundle export
• coordination operator/admin views plus explicit review-linkage into governance and proof follow-through
• admission ops/workflow packs, coordination packs, and zones dashboard packaging

The Wave D adapter-breadth line broadens the bundled public integration surface as well:

• additional built-in protocol surfaces for a2a, acp, mqtt, grpc, kafka, nats, and ros2
• additional built-in execution-front surfaces for langchain, langgraph, semantic_kernel, autogen, crewai, and llamaindex
• broader bundled payment and identity breadth through mpp and erc8004-oriented public integration surfaces

The Wave F shell carry-over line adds a bounded operator shell inside public xytara:

• self-serve agent account issuance for the public runtime path
• a unified operator shell summary across operations, economics, and coordination
• compact workflow/admin shell exports that point cleanly into proof-side follow-through when needed

This keeps the public product centered on naxytra while recovering the useful operator-shell lineage as a built-in xytara capability instead of a separate branded surface.

Verification

Local verification commands:

• npm run verify:package
• npm run verify:adapters
• npm run verify:tooling
• npm run verify:examples
• npm run verify:service
• npm run verify:all

The current verification covers:

• package exports and helper breadth
• adapter manifest and implementation conformance
• registry bundle tooling behavior
• quickstart behavior
• service-route behavior
• preserved operator/reporting surfaces

Control Files

• FINAL_CONTRACT.md
• TERMINOLOGY.md
• SERVICE_CONTRACT.md