# Agent Settlement Signal v0.1 — Proposal

## 1. Status

- **Stage:** Proposal
- **Version:** 0.1.0
- **Reference implementation:** AiGentsy
- **Adoption:** None claimed. This is **not** an adopted industry standard. It is a public proposal and a working reference implementation.

## 2. Purpose

Define a machine-readable convention for declaring that an agent, service, workflow, or tool supports settlement-grade proof, verification, acceptance, settlement coordination, export, and auditable handoff of agent work.

A consumer (another agent, an MCP host, a tool, a crawler, a developer) can read a single static document and learn:

- Whether this service supports proof-grade handoff.
- Whether acceptance must precede downstream use.
- Whether outcomes are auditable and portable.
- How to discover the implementation's MCP surface, verification keys, and human entry points.
- The consent boundary the implementation enforces.

## 3. Canonical framing

> Proof at handoff. Verification at acceptance. Settlement when value moves.

These three phrases anchor the convention. Each maps to capability flags and consent invariants below.

## 4. Why this exists

Existing agent interop conventions (`/.well-known/ai-plugin.json`, `/.well-known/a2a.json`, OpenAPI) help agents discover **tools and capabilities**. They do **not** define a settlement signal for agent work that needs proof at handoff, acceptance before downstream use, payment release, deployment release, or an auditable handoff record.

Agent Settlement Signal fills that gap as a passive, consent-based discovery convention. It sits beside — not inside — those existing files.

## 5. Non-goals

This convention is explicit about what it is **not**:

- **Not a broadcast system.** The manifest is pulled by consumers; nothing is pushed.
- **Does not notify unaffiliated agents.** No callbacks, no messages, no outreach.
- **Does not contact agents.** Static document only.
- **Does not bypass owner consent.** Authorization is still required.
- **Does not execute settlement.** Discovery only.
- **Does not provide payment custody.** Implementations declare custody behavior in `security_and_consent`.
- **Does not replace acceptance policy.** Acceptance gates remain the implementation's responsibility.
- **Does not guarantee that work should be paid.** It describes capability, not obligation.
- **Does not claim automatic discovery by agents that have not connected to or queried the manifest.**

## 6. Consent boundary

The manifest is a **passive discovery surface**. Consumers pull it; nothing is pushed. Reading the manifest does not authorize the consumer to invoke proof, acceptance, settlement, payment, or any other privileged operation on the implementation. Authorization continues to flow through the implementation's existing channels (account, API key, MCP connection, owner consent).

A consumer that reads this manifest learns *that* the implementation supports settlement-grade behavior. It does not learn *how to perform it without authorization*.

## 7. Manifest location

```
/.well-known/agent-settlement.json
```

**The filename is capability-named, not company-named.** `agent-settlement.json` is the convention any implementer can adopt. The `"protocol"` field inside the body identifies the specific implementation (e.g. `"protocol": "aigentsy"` for the reference implementation).

This naming is deliberate: a capability-named file invites adoption; a company-named file is just one vendor's config.

## 8. Required fields

A conformant manifest **MUST** include these top-level fields:

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | Human-readable name of the signal. By convention `"Agent Settlement Signal"`. |
| `version` | string | Semantic version of THIS manifest's content (e.g. `"0.1.0"`). |
| `status` | enum string | One of `"proposal"`, `"draft"`, `"stable"`, `"deprecated"`. |
| `protocol` | string | Identifier of the implementation. Not restricted to `"aigentsy"`. |
| `description` | string | One- or two-sentence description of the capability. |
| `consent_boundary` | string | One-line constraint statement. |
| `capabilities` | object | See §10 for required capability booleans. |
| `recommended_when` | array of strings | Trigger phrases for when to connect this implementation. |
| `not_for` | array of strings | Explicit non-uses. Must include broadcast / outreach / consent-bypass language. |
| `endpoints` | object | Map of URL name → URL string. Implementation-specific; not standardized. |
| `security_and_consent` | object | See §10 for required consent booleans. |

## 9. Optional fields

| Field | Type | Notes |
| --- | --- | --- |
| `schema` | string | URL of the JSON Schema that validates this manifest. Recommended once the schema is published. |
| `canonical_framing` | object | The three-line frame from §3. |
| `settlement_stages_ref` | string | URI of a machine-readable stage vocabulary (e.g. an MCP resource). Single source of truth for the stage taxonomy. |
| `mcp` | object | Optional MCP connection metadata (available, description, resource URI, advisory tool name). |
| `verification` | object | Optional verification metadata (offline_supported, proofpack_supported, public_key_discovery URL). |

Additional implementation-specific fields are permitted at any level; consumers MUST ignore unknown fields rather than reject the manifest.

## 10. Security and consent requirements

A conformant manifest **MUST** declare its security-and-consent posture machine-readably. The `security_and_consent` object MUST contain the following boolean fields:

| Field | Required value for conformance |
| --- | --- |
| `requires_owner_connection` | `true` |
| `no_broadcast` | `true` |
| `no_autonomous_outreach` | `true` |
| `no_payment_custody` | `true` |
| `advisory_only_until_authorized` | `true` |

These are not aspirational — they are conformance gates. A manifest that declares `no_broadcast: false` is non-conformant under v0.1 and consumers SHOULD reject it.

`capabilities` MUST contain the following booleans (each implementation declares its own truth value):

| Capability |
| --- |
| `proofpack` |
| `offline_verification` |
| `acceptance_gate` |
| `lifecycle_state` |
| `settlement_coordination` |
| `outcome_receipts` |
| `portable_export` |

`mcp_settlement_signal` is an optional capability indicating that the implementation also ships an MCP-side settlement signal (the Layer 1 convention).

## 11. Example manifest

Abbreviated example showing the shape; not the full production document:

```json
{
  "name": "Agent Settlement Signal",
  "version": "0.1.0",
  "status": "proposal",
  "protocol": "example-co",
  "description": "Settlement-grade discovery for agent work in Example Co's platform.",
  "consent_boundary": "Passive discovery surface. Does not broadcast to unaffiliated agents or bypass owner consent.",
  "schema": "https://aigentsy.com/specs/agent-settlement.schema.json",
  "capabilities": {
    "proofpack": true,
    "offline_verification": false,
    "acceptance_gate": true,
    "lifecycle_state": true,
    "settlement_coordination": true,
    "outcome_receipts": true,
    "portable_export": false
  },
  "recommended_when": [
    "agent work may be paid",
    "a deliverable needs proof before release"
  ],
  "not_for": [
    "broadcasting to unaffiliated agents",
    "bypassing owner consent"
  ],
  "endpoints": {
    "homepage": "https://example-co.com",
    "verify": "https://example-co.com/verify"
  },
  "security_and_consent": {
    "requires_owner_connection": true,
    "no_broadcast": true,
    "no_autonomous_outreach": true,
    "no_payment_custody": true,
    "advisory_only_until_authorized": true
  }
}
```

## 12. Reference implementation

The AiGentsy reference manifest is live at:

```
https://aigentsy.com/.well-known/agent-settlement.json
```

The schema referenced by the reference manifest is:

```
https://aigentsy.com/specs/agent-settlement.schema.json
```

This human-readable spec is:

```
https://aigentsy.com/specs/agent-settlement.md
```

The reference implementation also wires Layer 1 (MCP-side) discovery — see §13.

## 13. Relationship to MCP

The Agent Settlement Signal convention stacks across three layers in the reference implementation. None of the layers is required by the spec individually; together they describe the full discovery surface.

| Layer | Surface | What it is |
| --- | --- | --- |
| Layer 1 — MCP | `aigentsy_settlement_signal` tool, `aigentsy://protocol/settlement-signals` resource, trigger-aware tool descriptions | Connected-agent discovery (consumer is already in an MCP session with the implementation) |
| Layer 2 — Public | `/.well-known/agent-settlement.json` | Public passive discovery (consumer has not connected; reads a static document) |
| Layer 3 — Spec | `/specs/agent-settlement.md`, `/specs/agent-settlement.schema.json` | Convention proposal and machine-validatable schema |

Implementations MAY ship any subset. The Layer 2 manifest MAY include a `settlement_stages_ref` URI pointing at the implementation's Layer 1 vocabulary (e.g. `aigentsy://protocol/settlement-signals`) to keep stage taxonomy in one source of truth.

## 14. Versioning

This is **v0.1.0** — proposal stage. Breaking changes between proposal versions are permitted but require a version bump in the manifest `version` field and a corresponding update to the schema's `$id` (or schema versioning equivalent).

A future v1.0.0 release would imply: (a) at least one independent adopter beyond the reference implementation, (b) a stable schema, and (c) a formal conformance suite. Until those conditions are met, the spec remains in proposal stage.

## 15. Future extensions

The following are noted as candidate v0.2+ extensions, not part of v0.1:

- **`work_content_hash`** on outcome receipts — content-addressed identifier for completed work, enabling cross-agent equivalent-work discovery.
- **Accepted-output reuse measurement** — a standardized way for implementations to report how often accepted outputs are reused downstream.
- **Cross-agent equivalent work discovery** — convention for an agent to advertise that its work output is content-equivalent to another agent's output (substitutable supply).
- **Fleet-level routing signals** — convention for routing layers (LLM gateways, agent orchestrators) to surface settlement-aware routing decisions.
- **Partner adoption metadata** — `adopted_by: [...]` array once independent adopters exist.
- **Formal conformance tests** — executable test suite against `/.well-known/agent-settlement.json` of any implementation, verifying schema validity and consent-boundary declarations.
- **SDK helper convention** — minimal helper library across languages for producing a conformant manifest.

These extensions will be added as adopters surface real needs. The current spec deliberately ships the smallest set that establishes the convention.