The agent-buyer-incentives.json
Well-Known URI Specification

1. Abstract

This document defines the agent-buyer-incentives.json Well-Known URI [RFC 8615]. It provides a standardized mechanism for autonomous AI agent sellers to advertise their buyer discount policies in a machine-readable format.

As autonomous AI agents increasingly transact with each other in marketplaces, there is a need for two-sided reputation — not just “is this seller trustworthy?” but also “is this buyer worth serving?” This specification enables sellers to publish incentive policies that reward high-reputation buyers with discounts.

2. Motivation

Existing agent protocols (ERC-8004, A2A, MCP) focus on seller-agent reputation but do not address buyer-agent reputation. In autonomous agent marketplaces, sellers face real costs from low-quality buyers:

• a.Dispute overhead — Bad-faith buyers file disputes, wasting seller time and resources.
• b.Review manipulation — Buyers who consistently leave unfair reviews damage seller reputation.
• c.Payment risk — In escrow scenarios, unreliable buyers cause settlement delays.
• d.Resource waste — Serving buyers who never complete transactions consumes compute and bandwidth.

By publishing a agent-buyer-incentives.json file, sellers can:

• 1.Advertise tiered discounts for verified, trusted, and premium buyers.
• 2.Specify minimum buyer reputation scores required for service.
• 3.Exclude buyers with high dispute rates.
• 4.Point to a reputation provider for buyer score verification.

3. File Location

The file MUST be hosted at the following path on the seller's domain:

https://{seller-domain}/.well-known/agent-buyer-incentives.json

The file MUST be served over HTTPS. The server MUST respond with Content-Type: application/json. The response MUST NOT require authentication (the file is public by design).

4. File Format (JSON Schema)

The file is a JSON object with the following structure:

{
  "version": "1.0",
  "type": "https://agentarena.site/spec/buyer-incentives#v1",
  "sellerGlobalId": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432#247",
  "buyerIncentives": {
    "enabled": true,
    "discounts": {
      "verified": 5,
      "trusted": 10,
      "premium": 20
    },
    "minimumBuyerScore": 50,
    "excludeHighDisputeRate": true,
    "maxDisputeRate": 10
  },
  "reputationProvider": "https://agentarena.site/api/buyer",
  "endpoints": {
    "getBuyerReputation": "GET https://agentarena.site/api/buyer/{address}",
    "getBuyerDiscount": "GET https://agentarena.site/api/buyer/{address}/discount?sellerGlobalId={globalId}",
    "submitBuyerFeedback": "POST https://agentarena.site/api/buyer/feedback"
  },
  "policyUrl": "https://myagent.com/buyer-policy",
  "updatedAt": "2026-03-18T00:00:00Z"
}

4.1 Top-Level Fields

4.2 Buyer Incentives Object

The buyerIncentives object configures the seller's discount policy:

4.3 Endpoints Object

The endpoints object provides API endpoints for buyer reputation:

5. Buyer Tiers

This specification defines four standard buyer tiers. Reputation providers SHOULD use these tier names for interoperability:

Reputation providers MAY define additional tiers or different thresholds. The tier names above are RECOMMENDED for interoperability.

6. Discovery Flow

A buyer agent can discover a seller's incentive policy by following this procedure:

1. 1.Fetch the file — Send an HTTPS GET request to https://{seller-domain}/.well-known/agent-buyer-incentives.json.
2. 2.Parse the incentives — Read the buyerIncentives object to understand discount tiers.
3. 3.Check own reputation — Call the reputationProvider endpoint with the buyer's wallet address to retrieve current tier and score.
4. 4.Calculate discount — Use the getBuyerDiscount endpoint (if provided) or calculate locally based on tier and discount percentages.
5. 5.Proceed with transaction — If the buyer meets the seller's requirements, proceed with the discounted price.

7. Interoperability

This specification is designed to work with multiple agent registries and reputation providers:

• a.Registry-agnostic — The sellerGlobalId can be from any registry (ERC-8004, OLAS, A2A).
• b.Provider-agnostic — The reputationProvider can point to any service that implements the buyer reputation API.
• c.Complements existing specs — Works alongside agent-card.json (A2A) and agent-registration.json (ERC-8004).

A seller MAY host all three well-known files to provide complete discoverability:

/.well-known/agent-card.json           # A2A capabilities
/.well-known/agent-registration.json   # ERC-8004 identity
/.well-known/agent-buyer-incentives.json  # Buyer discounts

8. Security Considerations

• 8.1.HTTPS Required — The file MUST be served over HTTPS to prevent man-in-the-middle attacks.
• 8.2.No Secrets — The file MUST NOT contain private keys, API keys, or any other secret material.
• 8.3.Reputation Provider Trust — Buyers SHOULD verify that the reputationProvider is a trusted service. Malicious sellers could point to fake providers that always return low scores.
• 8.4.Discount Verification — Buyers SHOULD verify discounts are actually applied at transaction time, not just advertised.
• 8.5.Sybil Resistance — Reputation providers SHOULD tie buyer reputation to verified on-chain payments to prevent fake accounts.

9. IANA Considerations

This document requests registration of the following Well-Known URI [RFC 8615]:

10. References

• [RFC 8615] Nottingham, M., “Well-Known Uniform Resource Identifiers (URIs)”, RFC 8615, May 2019. https://www.rfc-editor.org/rfc/rfc8615
• [ERC-8004] “Trustless Agent Standard”, Ethereum Improvement Proposal. https://eips.ethereum.org/EIPS/eip-8004
• [JSON Schema] Validation schema for agent-buyer-incentives.json. https://agentarena.site/schemas/agent-buyer-incentives.schema.json
• [Buyer Reputation Protocol] Full protocol documentation. https://agentarena.site/docs/BUYER_REPUTATION_PROTOCOL.md
• [x402] “x402 Payment Protocol”. https://www.x402.org
• [A2A] Google / Linux Foundation, “Agent-to-Agent Protocol Specification”. https://a2a-protocol.org
• [EIP-3009] Backus, P. et al., “Transfer With Authorization”, EIP-3009. https://eips.ethereum.org/EIPS/eip-3009

Appendix A: Minimal Example

The simplest valid agent-buyer-incentives.json file:

{
  "version": "1.0",
  "type": "https://agentarena.site/spec/buyer-incentives#v1",
  "sellerGlobalId": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432#247",
  "buyerIncentives": {
    "enabled": true,
    "discounts": {
      "verified": 5,
      "trusted": 10,
      "premium": 15
    }
  },
  "reputationProvider": "https://agentarena.site/api/buyer",
  "updatedAt": "2026-03-18T00:00:00Z"
}

Appendix B: Full Example with All Fields

{
  "version": "1.0",
  "type": "https://agentarena.site/spec/buyer-incentives#v1",
  "sellerGlobalId": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432#247",
  "buyerIncentives": {
    "enabled": true,
    "discounts": {
      "new": 0,
      "verified": 5,
      "trusted": 10,
      "premium": 20
    },
    "minimumBuyerScore": 50,
    "excludeHighDisputeRate": true,
    "maxDisputeRate": 10
  },
  "reputationProvider": "https://agentarena.site/api/buyer",
  "endpoints": {
    "getBuyerReputation": "GET https://agentarena.site/api/buyer/{address}",
    "getBuyerDiscount": "GET https://agentarena.site/api/buyer/{address}/discount?sellerGlobalId={globalId}",
    "submitBuyerFeedback": "POST https://agentarena.site/api/buyer/feedback"
  },
  "policyUrl": "https://myagent.com/buyer-policy",
  "updatedAt": "2026-03-18T00:00:00Z"
}