Discovery

The /.well-known/legal-context.json discovery standard for advertising legal context availability.

Well-Known URI

A vendor implementing the Agent Legal Context (ALC) protocol MUST serve a JSON document at:

https://{domain}/.well-known/legal-context.json

The document MUST be served over HTTPS. The TLS certificate provides domain identity anchoring.

Discovery Document Schema

Required Fields

The discovery document MUST be a valid JSON object with at minimum these three fields:

{
  "version": "1.0",
  "contentHash": "0x7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069",
  "api": "https://api.integraledger.net/v1/records/0xabcdef1234567890"
}

Field	Type	Required	Description
`version`	string	REQUIRED	Protocol version. MUST be `"1.0"` for this specification.
`contentHash`	string	REQUIRED	SHA-256 hash of the current terms document. `0x`-prefixed, 64 hex characters (66 total).
`api`	string	REQUIRED	Absolute HTTPS URL of the ALC API endpoint. SHOULD include the recordId as a path segment.

Optional Fields

{
  "version": "1.0",
  "contentHash": "0x7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069",
  "api": "https://api.integraledger.net/v1/records/0xabcdef1234567890",
  "acceptanceRequired": false,
  "identity": {
    "domain": "example.com",
    "did": "did:web:example.com",
    "attestation": "0xabcdef...7890"
  },
  "terms": {
    "humanReadable": "https://example.com/terms",
    "machineReadable": "https://example.com/terms.json",
    "effectiveDate": "2026-03-01T00:00:00Z"
  },
  "capabilities": ["record", "dispute", "identity", "compliance"]
}

Field	Type	Description
`acceptanceRequired`	boolean	If `true`, counterparties MUST explicitly accept terms (Tier 2) before transacting. Default: `false`.
`identity.domain`	string	The domain this file is served from. MUST match the TLS certificate.
`identity.did`	string	A Decentralized Identifier bound to this domain.
`identity.attestation`	string	An on-chain attestation UID linking to verified identity.
`terms.humanReadable`	string	URL of the human-readable terms document.
`terms.machineReadable`	string	URL of a structured, machine-readable terms representation.
`terms.effectiveDate`	string	ISO 8601 date-time when the current terms took effect.
`capabilities`	array	List of ALC capabilities supported by the API endpoint.

Defined Capability Values

Capability	Description	API Endpoints Implied
`"record"`	IntegraRecord creation and query	`POST /v1/records`, `GET /v1/records/{recordId}`
`"terms"`	Terms document retrieval and verification	`GET /v1/records/{recordId}/terms`, `GET /v1/verify/{contentHash}`
`"accept"`	Explicit terms acceptance (Tier 2)	`POST /v1/records/{recordId}/accept`
`"contact"`	Contact information retrieval	`GET /v1/records/{recordId}/contact`
`"dispute"`	Dispute resolution (filing and status)	`GET /v1/records/{recordId}/dispute`, `POST /v1/records/{recordId}/disputes`
`"identity"`	Identity attestation verification	Implementation-defined
`"compliance"`	Compliance checking	Implementation-defined
`"escrow"`	Escrow management	Implementation-defined
`"negotiation"`	Negotiation boundary enforcement (Tier 3)	Implementation-defined

The capability set is extensible. Implementations MAY define additional capability strings using a namespaced format (e.g., "alc:ext:custom-capability").

Agent Discovery in Protocol Metadata

When an agent advertises itself via any discovery mechanism (A2A Agent Cards, MCP tool manifests, ACP discovery, or similar), it SHOULD include an integra field in its metadata. (The "integra" key name follows the Integra reference implementation convention.)

{
  "name": "Acme Compute Agent",
  "capabilities": ["compute", "inference"],
  "integra": {
    "contentHash": "0x7f83b165...",
    "api": "https://api.integraledger.net/v1/records/0xabcdef..."
  }
}

This tells any counterparty: the agent transacts under terms identified by the given contentHash, verifiable via the given API endpoint.

The /.well-known/legal-context.json discovery document uses a flat top-level structure. When ALC metadata is embedded inside another protocol's JSON structure, it SHOULD be nested under an "integra" key (following the reference implementation convention) to avoid field name collisions.

Caching

Clients SHOULD cache the discovery document for a period not exceeding 24 hours. Clients MUST re-fetch after cache expiry. Vendors MAY include standard HTTP cache headers (Cache-Control, ETag, Last-Modified) to control caching behavior.

Complete Examples

Minimal (Tier 1)

{
  "version": "1.0",
  "contentHash": "0x7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069",
  "api": "https://api.integraledger.net/v1/records/0xabcdef1234567890"
}

Standard (Tier 1 with optional fields)

{
  "version": "1.0",
  "contentHash": "0x7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069",
  "api": "https://api.integraledger.net/v1/records/0xabcdef1234567890",
  "acceptanceRequired": false,
  "identity": {
    "domain": "example.com",
    "did": "did:web:example.com"
  },
  "terms": {
    "humanReadable": "https://example.com/terms",
    "effectiveDate": "2026-03-01T00:00:00Z"
  },
  "capabilities": ["record", "dispute", "identity"]
}

Full (Tier 2 with all fields)

{
  "version": "1.0",
  "contentHash": "0x7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069",
  "api": "https://api.integraledger.net/v1/records/0xabcdef1234567890",
  "acceptanceRequired": true,
  "identity": {
    "domain": "example.com",
    "did": "did:web:example.com",
    "attestation": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "terms": {
    "humanReadable": "https://example.com/terms",
    "machineReadable": "https://example.com/terms.json",
    "effectiveDate": "2026-03-01T00:00:00Z"
  },
  "capabilities": ["record", "dispute", "identity", "compliance", "escrow", "negotiation"]
}

IANA Registration

The /.well-known/legal-context.json URI will be submitted for registration with IANA per RFC 8615. This is the same registry used by /.well-known/openid-configuration, /.well-known/agent-card.json (A2A), and /.well-known/ucp (UCP).

Field	Value
URI suffix	`legal-context.json`
Change controller	Integra Ledger
Status	Provisional

Normative References

RFC 8615 -- Well-Known Uniform Resource Identifiers (URIs)
RFC 2119 -- Key words for use in RFCs to Indicate Requirement Levels
RFC 9457 -- Problem Details for HTTP APIs (used for error responses)

On this page