Agent-Ready Product Catalogs: What GOAT's agent.md and manifest.json Actually Convey

An agent-ready product catalog needs to answer two different questions: is this the right offer, and can this buyer purchase it through a trustworthy interface? A file named agent.md does not answer either question by itself. Nor does valid JSON establish a complete product contract.

In GOAT Flow, agent.md and manifest.json are product-specific public entry surfaces associated with QuickPay and PayKit. They help a client discover a merchant's payment capabilities and offers. They are not universal commerce standards, and they should not be treated as an arbitrary container for every license, delivery or service promise a merchant wants to publish.

The merchant's task is to make the documented payment surface accurate while keeping the rest of the commercial offer explicit and consistent. Adding invented fields is less useful than identifying which system actually owns each promise.

Start With the Consuming Client, Not the Filename

The same-looking filenames occur in unrelated agent tools. A coding assistant's instruction file, an agent's system-prompt manifest and a merchant payment guide can all use Markdown or JSON while carrying entirely different meanings. Copying a format from one into another does not establish compatibility.

Start by identifying the client expected to consume the catalog. For GOAT Flow's public payer tooling, that is the PayKit/QuickPay interface described in its current documentation. The merchant's public payment page serves a person; the agent guide supplies readable entry information; the manifest supplies structured discovery data. Their shared merchant identity matters more than their extensions.

Copy the actual merchant links from the applicable portal rather than constructing URLs from a marketing website. GOAT's product page, merchant portal, QuickPay origin and authenticated API origin serve different roles. A valid website address is not necessarily a checkout origin or a merchant API base URL.

Current documentation accepts both the newer /paykit/ merchant-link prefix and legacy /quickpay/ links, with optional agent.md or manifest.json suffixes. Legacy link acceptance does not mean every old package command refers to the newest package. PayKit has a current package name while repository directory names can retain historical names. Check the documentation for the client being deployed rather than inferring behavior from a directory label.

This public surface also does not establish discovery distribution. An agent given the link may inspect it; publishing the file does not prove that every assistant will find, index or recommend the merchant. Catalog readability and channel access are separate problems. Treat any claim about search visibility or automatic buyer reach as requiring evidence beyond the presence of these files.

Publish the Fields GOAT Actually Documents

For fixed QuickPay Products, the current GOAT Flow merchant guide documents a deliberately small public field set: product_key, name, optional description, optional image_url and a positive decimal price. The product key is an integration identifier, not merely a display label. The name helps identify the item; the description can clarify its meaning without becoming an executable contract.

The documented product-key format permits letters, digits and the specified punctuation characters, with a bounded length. Rather than deriving keys from mutable marketing titles, choose stable identifiers that remain meaningful to your order system. A title can change for clarity without turning every existing reference into a different purchase target.

Keep decimal prices as decimal representations, not informal text such as “about twenty dollars.” The interface must distinguish a product's price from promotional prose and from quantities expressed in token base units. The buyer's selected payment method and the server's quote determine how the actual payment is represented. Do not assume that every price-looking value in a manifest uses the same unit.

The portal also exposes enabled and sort_order, but the current merchant guide says those fields are not exported or validated by the public QuickPay client and are not currently published in the public manifest. That is a boundary of the checked contract. It is not permission to add them to a hand-built manifest and assume every consuming client will enforce them.

Likewise, distinguish the raw manifest from an inspection summary. PayKit's documented inspect output groups Crypto products under x402_products and Card products under fiat_products. Those are documented inspection-output names; they should not be copied into a supposed raw-manifest schema without checking the raw interface. A normalized client view can rename or organize data for convenience.

The practical rule is to preserve the provider's actual public contract and validate against the version you use. If a desired attribute is not documented, ask whether the client supports it before relying on it. A parser accepting unknown JSON properties does not establish that those properties affect purchase behavior.

Describe Payment Methods Without Inventing Availability

Product existence and payment eligibility are different facts. A merchant can have an offer while lacking a usable receiving configuration for the buyer's chosen asset or environment. A public catalog should describe the actual enabled methods rather than copy a protocol-wide chain list or another merchant's screenshot.

In GOAT Flow, available chains, token contracts, decimals, amount limits and receiving configuration are deployment- and merchant-specific. Use the active portal and public discovery response appropriate to the environment. Testnet configuration does not establish Mainnet availability. A repository type that recognizes an asset or payment method is not evidence that the merchant can currently accept it.

The same principle applies to Card. A product can be advertised for Crypto, Card or both according to its configuration. A buyer should understand whether it needs a wallet and native gas for the selected crypto path or must hand off to a human payer for hosted card completion. Current PayKit Card-link creation does not collect card credentials or confirm payment autonomously.

For catalog operators, separate the existence of a method from its operational prerequisites. A payment link may be valid while a merchant capability is unavailable or a chosen pair is not configured. Conversely, a feature not described by a particular document may still exist in a specific deployment. Resolve that uncertainty through runtime responses and deployment confirmation rather than declaring the feature universally absent or enabled.

Do not flatten every payment rail into one generic “pay now” action. A fixed Product, a buyer-entered custom amount and a paid API route have different purchase semantics. The first represents a merchant-defined item; the second lets the payer choose an amount; the third identifies a protected resource under a particular payment profile. An agent needs those distinctions to select an appropriate action.

If a rail or product is disabled after a buyer has begun a purchase, the recovery policy must account for the existing intent. A changed discovery response is not proof that an earlier transfer did not happen. Keep catalog freshness and payment reconciliation separate so a configuration change does not trigger unnecessary new purchases.

Discovery Must Yield to the Current Payment Instruction

The trusted link is an important boundary in GOAT's payer tooling. PayKit takes the merchant identity from the trusted URL and validates that the fetched manifest identifies the same merchant. It derives payment endpoints from that origin rather than trusting arbitrary absolute endpoint URLs supplied in the manifest. The documented HTTPS requirement, except for loopback development, protects this discovery path from simple plaintext substitution.

That does not make every description on the trusted host a buyer authorization. The agent still needs permission from its owner to spend the relevant amount on the relevant offer. Public merchant text should be treated as seller-supplied information, not as instructions to override the buyer's budget or disclose credentials.

Nor is the manifest the final transfer instruction. It is discovery and preflight data. The returned payment session or challenge supplies the current authoritative terms for execution. A cached product price can help the client detect disagreement, but it should not be used to reconstruct a recipient, token amount or expiry when the server returns different terms.

For the documented Crypto Product path, the client converts the manifest price using the selected token's decimals and checks the returned session amount before broadcasting. A mismatch should produce a controlled stop, not an improvised transfer based on whichever number the agent prefers. This check connects advertised price to payment execution without making the catalog the payment-verification system.

Paid API routes need an additional distinction. GOAT Flow's current MPP integration uses GOAT-specific JSON challenge and verification endpoints and a signed three-segment Payment-Receipt extension. It is not the generic MPP HTTP wire format, and the checked docs do not establish interoperability with official MPP SDKs. Publishing an MPP route in a manifest does not prove arbitrary MPP clients can purchase it unchanged.

The profile's merchant middleware checks receipt authenticity, merchant audience, route binding and expiry; replay protection additionally depends on a configured receipt-ID store. A receipt valid for that profile is not a license for every catalog item, a generic checkout confirmation or evidence that the buyer received the promised business output. Do not infer payment-channel, subscription or unlimited-use behavior merely from the MPP label.

The distinction matters during failure. If payment may have been broadcast but verification failed, preserve the existing transaction and challenge context. Refreshing discovery does not erase that transaction. The catalog can help a buyer find the offer; it cannot decide that another charge is necessary simply because an execution attempt timed out.

Keep the Rest of the Product Promise in Merchant-Owned Records

A compact payment manifest cannot carry the entire meaning of a product. A buyer may still need to know the asset version, permitted use, delivery format, required input or support policy. Publish those facts through a merchant-controlled product surface and keep them aligned with the payable offer. Do not assume unsupported field names will be understood by PayKit.

The following is an ownership guide, not a proposed JSON schema:

Consider a hypothetical merchant selling a licensed research report. The payment product can identify the fixed offer and price. The merchant's own specification should explain the report edition, file format, intended audience, license scope and whether updates are included. Those properties help the buying agent decide suitability; they are not automatically validated because the merchant adds similarly named JSON properties somewhere.

Keep a merchant-owned mapping between the public product key and that commercial specification. When an order is created, preserve the relevant offer version in the business record. The particular data model is the merchant's choice. It should not be presented as a built-in QuickPay metadata feature unless the selected integration actually documents and supports it.

The description field can summarize essential limitations, but do not bury contradictory terms in a linked page. If the catalog says a report includes future editions and the controlling terms exclude them, the problem is substantive, not a formatting defect. One accurate offer should govern the buyer-facing page, agent-readable explanation and purchase record.

Public readability also imposes a confidentiality boundary. Publish descriptive product information, not paid download credentials, software activation secrets or merchant API keys. A catalog is meant to be fetched by prospective buyers. Successful parsing must not grant access to the thing being sold or reveal the credentials used to manage the merchant account.

For physical goods, shipping conditions may require other records and interfaces. For services, input validity and capacity acceptance matter. The small payment Product contract should not be stretched into an undocumented universal order model. Select an integration that can carry the required business information, or keep an explicit merchant-owned association outside the public payment manifest.

Change an Offer Without Breaking Its Meaning

A catalog is not finished when its first manifest parses. Prices change, editions expire and delivery policies evolve. Assign an owner for the commercial specification and another, if necessary, for payment configuration. Define how those owners coordinate a material change so the public offer and the server quote do not contradict each other during rollout.

Not every edit needs a new product identity. Correcting a typo in the name may leave the same purchased promise intact. Replacing an edition, changing permitted use or switching from a perpetual download to temporary access can change the offer materially. Consider a distinct product or variant identity when reusing the old key would make historical purchases ambiguous.

Preserve the version that an existing buyer actually purchased. A current manifest describes current discovery, not necessarily the terms of a previous order. Keeping an order snapshot lets support determine whether a buyer is entitled to an older report edition or an update. It also prevents a catalog migration from silently rewriting obligations already created.

Treat caching as an expected condition. An agent can inspect an offer, pause for human approval and return after the merchant updates it. A later price or availability mismatch should lead to re-evaluation or renewed approval under the buyer's policy. It should not lead the agent to bypass validation, choose a different recipient or silently accept a more expensive offer.

Documentation changes need similar care. The legacy GOAT repository URL now redirects to the canonical GOATNetwork/goat-flow repository. Some indexed excerpts retain earlier package-version language while current pages record later publication verification. Resolve behavior against the current relevant documentation and the actual deployed client; a search snippet or old example is not a reliable compatibility contract.

For one offer, the merchant should be able to point to an unambiguous product identifier, a current payment discovery surface, a controlling commercial specification and a record of the terms accepted at purchase. That is a useful agent-ready catalog even if the public payment schema remains small. Completeness comes from consistent ownership and enforceable boundaries, not from giving every business promise a new manifest key.

FAQ

Are agent.md and manifest.json universal product catalog standards?

No. Their meaning depends on the consuming client. In the GOAT Flow interface reviewed here, they are merchant payment-discovery surfaces associated with QuickPay and PayKit. An unrelated tool can use similar filenames for a different purpose. Follow the documented client contract rather than assuming filename compatibility.

Which fixed-product fields should I rely on in the documented public interface?

The reviewed QuickPay Product contract documents product_key, name, a positive decimal price and optional description and image_url. Portal controls and normalized inspection-output fields are not automatically raw-manifest fields. Check the actual interface and client version before relying on a property to affect purchase behavior.

Can a cached manifest price authorize the final transfer?

No. Discovery data helps the buyer evaluate an offer, but the current session or challenge supplies execution terms. The documented Crypto Product path checks the quoted amount against the advertised price before broadcast. A mismatch requires a controlled stop or renewed approval, not choosing whichever value is more convenient.

Where should license terms and paid-access secrets live?

Keep commercial terms on a merchant-controlled product surface and associate the accepted version with the purchase record. Do not assume unsupported manifest keys are enforced. Merchant API keys, activation secrets and paid-download credentials must stay out of public discovery data; understanding the offer must not itself unlock the asset.