Governance And Billing
Billing, idempotency, availability, health, and review rules for Xenodia marketplace capabilities.
Capabilities run through Xenodia's existing account, credit, and audit layer. Agents do not pay providers directly at invoke time; they call Xenodia, Xenodia reserves or charges credit, and the call is logged with capability-specific dimensions.
Billing Modes
Capability descriptors expose funding_modes. Current modes can include:
| Mode | Meaning |
|---|---|
owner_only | Charge the owner account. |
self_only | Charge the calling account. |
self_then_owner | Prefer self-funded credit, then fall back to owner-funded credit when policy allows. |
The response billing object shows the actual actor and payer selected for a call.
Price Units
Prices use micro USDC:
| Value | Meaning |
|---|---|
1 | 0.000001 USDC |
10000 | 0.01 USDC |
1000000 | 1 USDC |
For multi-operation capabilities, read operations[].pricing.unit_price_micro_usdc. Root-level pricing may be omitted from list responses when operations have distinct prices.
Funds And Failure Behavior
The capability runtime distinguishes between blocked calls and admitted calls:
| Case | Funds behavior |
|---|---|
| Hidden, disabled, unpublished contract, contract drift, or runtime not ready before invoke | No funds are locked. |
| Provider becomes unavailable after funds are reserved | Reserved funds are released when execution fails. |
| Successful admitted paid call | Actual amount is committed in the billing summary. |
| Idempotent replay | The stored result is returned without double-charging the same intent. |
Idempotency Policy
Require Idempotency-Key for:
- Paid operations.
- Async operations.
- Operations with
idempotency_key_required: true.
Agents should use deterministic retry keys for the same user intent and different keys for new user intents. A conflicting payload returns 409 idempotency_conflict.
Availability States
| State | Meaning |
|---|---|
active | Listing, detail, and invoke are allowed. |
hidden | Capability should not be visible to consumers. |
disabled | Capability is intentionally unavailable. |
not_configured | Runtime adapter or execution path is missing. |
contract_unpublished | A versioned runtime snapshot has not been published yet. |
contract_drift | Runtime contract differs from the frozen snapshot. |
suppressed | Health checks are suppressing new traffic. |
Blocked responses include reason, retryable, effective_status, and no_funds_locked when available.
Health And Suppression
Provider health checks can suppress new traffic without hiding the documentation. Some helper operations may remain allowed while the main operation is suppressed so agents can inspect freshness and coverage.
Agents should treat suppressed or degraded health as a trust signal, not just a retry condition.
Audit Fields
Capability calls are recorded with capability-specific dimensions:
| Field | Purpose |
|---|---|
request_id | Idempotent request and billing correlation. |
model | Stored as capability/{slug} for gateway call records. |
capability_slug | Capability identifier. |
capability_operation | Operation identifier. |
capability_version | Published contract version. |
execution_mode | sync or async. |
actor | Calling account. |
payer | Charged account. |
blocked_before_invoke | Whether the call was rejected before funds were locked. |
Review Rules
A capability should not become consumer-visible unless:
- It has a versioned contract snapshot.
- Runtime readiness checks pass.
- Pricing is visible before invoke.
- Paid operations require idempotency.
- Health failures do not silently charge users.
- Provider-facing names do not expose private routing internals.
- Agent docs explain the safest flow in operational language.