Agent card

For every verified site, Sill publishes a signed, A2A-compatible agent card at its edge. The agent card is the canonical, machine-readable identity + capability statement for the site’s Sill surface.

Endpoint

GET https://edge.sill.so/v1/agent-card/{site_key}.json

The card is A2A-compatible: A2A’s discovery convention is the well-known path /.well-known/agent-card.json. Sill’s edge serves the per-site card at the URL above; you can publish the per-site URL anywhere an A2A client will accept a card location.

What it contains

protocol_version: "a2a/1.2"
name: the site’s domain (A2A v1.0 required).
description: a short domain-of-action sentence (A2A v1.0 required). Bounded to 200 UTF-8 bytes at build time; a merchant-authored description rides here when present, otherwise a generic per-domain line is emitted so the field is always populated. The merchant’s full description still lives in the trimmable profile field.
version: "1.0" — the agent’s version string (A2A v1.0 required).
supportedInterfaces[]: A2A v1.0 interface list. Each entry carries url, protocolBinding, and protocolVersion, describing the actual transport at each URL — the MCP wrapper as JSONRPC / 2.0, and the signed ARD catalog as HTTP+JSON / 1.0.
defaultInputModes / defaultOutputModes: ["application/json"] (A2A v1.0 required). Sill skills exchange JSON.
skills[]: the site’s exposed agent skills, in the A2A-conformant per-skill shape. The skill set is backing-filtered — only skills the site actually exposes through a wired backing appear here. No overclaim. The set is published the moment the site’s domain proof lands, so the card reflects the merchant’s real skill selection from first eligibility.
capabilities: A2A transport-flags object.
mcp_endpoint: the per-site MCP wrapper URL, mirrored as a supportedInterfaces[] entry.
catalog_endpoint: the signed ARD catalog URL for the same site (https://edge.sill.so/v1/catalog/{site_key}.json), mirrored as a supportedInterfaces[] entry. A reader that fetches the card reaches the MCP endpoint and the catalog transitively — the card is the single discovery hub.
signing.algorithm: "ed25519".
signing.signing_key_id: the public key alias (matches the kid in the JWKS).
signing.issued_at / signing.expires_at: ISO-8601 UTC timestamps.
signing.envelope_signature: ed25519 signature over the JCS-canonical form of the card with envelope_signature removed. Every other field — including name, description, version, supportedInterfaces, defaultInputModes, defaultOutputModes, mcp_endpoint, catalog_endpoint, and the signing.* timestamps and key id — is bound by the signature.

Signing

The agent card is signed with Sill’s ed25519 card-signing key. The same public key is published in Sill’s JWKS with kty: "OKP", crv: "Ed25519", alg: "EdDSA", use: "sig". The kid in the JWKS matches the signing.signing_key_id on the card, so a verifier can resolve key → public bytes → verify in one step.

The JWKS endpoint:

GET https://edge.sill.so/.well-known/jwks.json

Any third party can fetch the JWKS and verify the agent card’s signature without any Sill-specific code. See Verify a signature.

Endpoint behavior

Unknown / malformed site_key → 404 with a constant {"error":"not_found"} body. Anti-fingerprinting: an unknown key is indistinguishable from a malformed one.
Resolved site that has not yet completed domain verification → 404 with a {"status":"pending_verification","message":"…"} body explaining that the card activates once the domain is verified. The 404 is deliberate — agents should still treat the site as having no live card and skip agent requests — but the body tells a human hitting the URL why it is empty.
Verified site → 200 with the signed card. Cache-Control: public, max-age=60, aligned with the signed expires_at.
The site’s enabled skill set is published to the card at the moment domain proof lands, so a freshly verified site’s card reflects the merchant’s real skill selection from first request.

Scope of claim

The signed card advertises capabilities — it is a discovery surface, not a guarantee that every advertised skill is dispatchable today.
Money-movement skills dispatch only through the signed-mandate path when payments are enabled. The card surface does not claim per-skill availability or SLA.
Sill claims no uptime SLA for this endpoint.