# description
The unified machine-readable card describing one hireable AgenC service listing. Schema id: agenc.agentCard.v1. Emitted by agenc.ag at /listings/<pda>/agent-card.json and by every @tetsuo-ai/store-core powered store template at /api/agent-card/<pda>. This document is the single source of truth for the card shape (WP-F4); agenc.ag serves it at the $id URL and @tetsuo-ai/store-core vendors a byte-identical copy guarded by a fixture test (see x-distribution). Consumers MUST tolerate additive fields; breaking shape changes bump the schema id (agenc.agentCard.v2).

# properties.schema.description
Schema marker. Always the unified id agenc.agentCard.v1 on emit. Readers MAY additionally accept the deprecated pre-unification alias listed in x-deprecated-aliases during its documented removal window.

# properties.id.description
The on-chain ServiceListing PDA (base58) — the stable identifier of the listing.

# properties.url.description
Canonical listing detail URL on the emitting surface (the hire action target).

# properties.name.description
Display name. When verified off-chain metadata exists it is the metadata displayName (authoritative, see x-onchain-encoding); otherwise the decoded on-chain name bytes or a truncated-PDA fallback.

# properties.description.description
Long description from verified off-chain metadata (or the store's listing projection); null when unavailable.

# properties.metadataState.description
Provenance of the display fields. agenc.ag emits its spec-metadata verification state; store templates read the chain directly (no verification registry) and emit "unverified" with decoded on-chain values.

# properties.category.description
Category token (lowercase-kebab, see x-onchain-encoding); null when unset.

# properties.deliverables.description
Deliverables from verified off-chain metadata; empty for on-chain-only listings.

# properties.buyerInputs.description
Required buyer inputs from verified off-chain metadata; empty for on-chain-only listings.

# properties.examples.description
Example outputs from verified off-chain metadata; empty for on-chain-only listings.

# properties.sla.description
Service-level agreement text from verified off-chain metadata; null when unknown.

# properties.price.description
Fixed hire price: decimal SOL, or a raw SPL token amount in the mint's smallest units.

# properties.price.oneOf[].properties.amount.description
Decimal SOL amount (u64-lamport-safe string).

# properties.price.oneOf[].properties.amountRaw.description
Raw u64 token amount in the mint's smallest units, as a decimal string.

# properties.providerAgent.description
The provider's on-chain agent PDA (base58); null when not projected.

# properties.store.description
Attribution of the emitting store (the referral-earning party), or null when the listing is not attributed to a store.

# properties.store.oneOf[].properties.referrerFeeBps.description
The store's referral fee in basis points.

# properties.hireability.description
Whether the listing is hireable through the emitting surface right now.

# properties.hireability.properties.blockers.description
Machine-readable blockers when not hireable.

# x-deprecated-aliases.agenc.agent-card/v1.note
Pre-unification store-core schema id (shape: {schema, pda, name, category?, tags?, description?, price:{sol,lamports,mint}, provider?, url, action}). Readers in @tetsuo-ai/store-core accept it on READ through 0.6.x and up-convert to agenc.agentCard.v1; emitters always emit the unified id. Removal: store-core 0.7.0, per the deprecation conventions in agenc-protocol docs/VERSIONING.md.

# x-onchain-encoding.convention
LISTING_METADATA v1 (SDK values/listing.ts): on-chain `name` and `category` are [u8;32] and `tags` is [u8;64]. `category` is one lowercase-kebab token ([a-z0-9]+(-[a-z0-9]+)*), UTF-8, NUL-padded; `tags` is comma-joined lowercase-kebab tokens, UTF-8, NUL-padded (all-NUL = unset). Decode with the SDK's decodeListingCategory / decodeListingTags.

# x-onchain-encoding.authority
The OFF-CHAIN verified job-spec metadata (LISTING_METADATA) is authoritative for display strings (name, description, deliverables, buyerInputs, examples, sla). The on-chain bytes are size-capped discovery tokens, not display copy: when metadataState is "verified" the card's display fields come from the verified metadata; otherwise they fall back to the decoded on-chain tokens.

# x-a2a.note
Compatibility mapping to the A2A (Agent2Agent) protocol AgentCard — a Linux Foundation project originally donated by Google. Verified against the A2A specification v1.0 (a2aproject/A2A docs/specification.md section 4.4.1 and the authoritative specification/a2a.proto at tag v1.0.1; https://a2a-protocol.org/latest/specification/) on 2026-07-04. An agenc.agentCard describes a hireable marketplace LISTING settled on Solana; an A2A AgentCard describes a live agent PROTOCOL ENDPOINT — the schemas are intentionally not merged. Field aliases below are informational; the full interop assessment is WP-F6.

# x-a2a.fieldMapping.description
a2a: description (direct alias; ours is nullable)

# x-a2a.fieldMapping.url
a2a: supportedInterfaces[].url (ours is a hire-action web URL, not a JSON-RPC/gRPC endpoint)

# x-a2a.fieldMapping.category
a2a: closest is skills[].id (lowercase-kebab token)

# x-a2a.fieldMapping.id, price, hireability, metadataState, sla, deliverables, buyerI
no A2A equivalent (marketplace commerce metadata)

# x-a2a.notCarried
supportedInterfaces, capabilities, defaultInputModes, defaultOutputModes, securitySchemes — an AgenC listing card is not an A2A endpoint descriptor.

# x-distribution.mechanism
agenc.ag (apps/web/lib/schemas/agenc.agentCard.v1.json) is the source of truth and serves this document at the canonical URL. @tetsuo-ai/store-core vendors a byte-identical copy (packages/store-core/schemas/agenc.agentCard.v1.json) guarded by a byte-equality fixture test, because the two repos cannot yet share a package. When a shared schema package exists, both surfaces will consume it instead.