EIP.tools

EIP.tools

⚠️ DraftStandards Track: ERC

ERC-8478: x402 Payee Verification for ERC-8004 Agents

How a paying agent proves an x402 payTo belongs to the ERC-8004 agent it means to pay, before it signs the payment

Authors
Created2026-10-30
Discussion Linkhttps://ethereum-magicians.org/t/erc-8478-x402-payee-verification-for-erc-8004-agents/30137
Requires

Markdown

https://raw.githubusercontent.com/ethereum/ERCs/re...
Pull Request#2132PR open

EIP-GPT summary

Contents
AbstractMotivationSpecificationTerms1. Naming the seller's identity2. The payee binding3. Payee delegation4. Verification and outcomes5. Signed payment6. DiscoveryRationaleBackwards CompatibilityTest CasesReference ImplementationSecurity ConsiderationsCopyright

Abstract

An agent that pays another agent over the x402 HTTP payment flow receives a payTo address in the server's 402 Payment Required answer and signs a payment to it. Nothing today ties that address to the paid agent's ERC-8004 identity: whoever controls the HTTP answer chooses where the money goes. This proposal defines (1) how an x402 payment requirement names the ERC-8004 identity it is paid to, (2) a payee binding: the payTo is the identity's registered agentWallet, or the agentWallet signed an EIP-712 payee delegation naming that payTo, and (3) a verification procedure a payer, wallet, facilitator or third-party checker runs before the payment is signed, with a fixed set of outcomes. The outcome is a fact about the binding, read at a stated block; it is never a score, and not read is never the same as verified or mismatch.

Motivation

x402 lets a client pay for an HTTP resource with a signed stablecoin transfer (for example an ERC-3009 transferWithAuthorization). The server's 402 answer lists what it accepts: a network, an asset, an amount and a payTo. The client signs a transfer to that payTo. For a person clicking "pay" in a browser that is the same trust as any checkout page. For an agent that pays other agents without a person reading each payment, it is a gap:

  • The HTTP answer is the only source of payTo. A compromised server, a hijacked domain, a reverse proxy, a malicious middleware, or an injected instruction in a tool result can change it. The payment still settles, the resource may even be delivered, and the money is gone.
  • ERC-8004 already has the right anchor and nobody checks it. An ERC-8004 identity can register an agentWallet, set by a signature of that wallet, so the address is proven to be under the agent's control. It is the natural place to receive payments, yet no rule says a payer should compare it with payTo.
  • Measured on one chain, the binding almost never holds today. On Robinhood Chain (chain id 4663) the ERC-8004 identity registry held 20,046 agents on 2026-10-28. 5,575 of them answered with an x402 payment requirement; in only 5 of those was payTo the agent's registered agentWallet. Almost all of the mismatches come from one operator that runs many agents and receives into one treasury, which is a legitimate setup: it is exactly the case a delegation must cover, so that a payer can tell a treasury the agent authorised from an address nobody did.

A payer cannot fix this alone, because it cannot tell a legitimate treasury from a substituted address. The seller cannot fix it alone, because a payer has no rule to check against. This proposal gives both sides the same rule.

Prior work: ERC-8004 defines the identity and agentWallet but not how payments bind to it. The Signed Payment Quotes proposal (a separate draft) defines a quote a provider signs for a payment, which proves who quoted a price but not that the quoted payTo is the agent's. The Prepared Transaction Envelope proposal (a separate draft) has a consumer-filled risk field where the outcome of this check fits as one warning among others.

Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Terms

  • Seller: the ERC-8004 agent that serves an x402 resource and is paid for it.
  • Payer: the party that signs the payment (an agent, its wallet, or a person).
  • Checker: whoever runs the verification in this proposal: the payer itself, its wallet, the facilitator, or a third-party service the payer asks.
  • Identity registry: an ERC-8004 identity registry, named by chain id and address.
  • Agent wallet: the address getAgentWallet(agentId) returns in the identity registry.
  • Payment requirement: one entry of the 402 answer's accepts list, with at least network, asset, an amount and payTo.

1. Naming the seller's identity

A seller that supports this proposal MUST name its ERC-8004 identity in every payment requirement, inside the entry's extra object, under the key erc8004:

{
  "scheme": "exact",
  "network": "eip155:4663",
  "asset": "0x…",
  "amount": "50000",
  "payTo": "0x…",
  "resource": "https://example.com/api/thing",
  "extra": {
    "erc8004": {
      "registry": "eip155:4663:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
      "agentId": "20030",
      "delegation": null
    }
  }
}
  • registry is a CAIP-10 account id: the chain and address of the identity registry. It MAY be on a different chain than network.
  • agentId is the token id as a decimal string.
  • delegation is either null or a payee delegation (section 3), REQUIRED when payTo is not the agent wallet.

A payer MAY also learn the identity some other way (it chose the seller from a directory by agentId, or the seller's registration file lists the resource). A requirement that names no identity and a payer that knows none is outcome no-identity.

2. The payee binding

A payment requirement is bound to the identity (registry, agentId) at block B of the registry's chain when all of the following hold:

  1. Endpoint: the resource's origin (scheme, host and port of resource, or of the URL the payer requested when the entry has no resource) is listed among the endpoints of the agent's registration file, the document at the identity's tokenURI as read at B. An origin matches when an endpoint URL in the file has the same scheme, host and port. Host comparison is case-insensitive and on the ASCII (punycode) form.
  2. Payee: one of
    • (a) payTo equals the agent wallet at B, compared as addresses (case-insensitive hex), and network is the registry's chain, or the agent wallet has no contract code on the registry's chain (an externally owned account controls the same address on every EVM chain). Code that is exactly the 23-byte EIP-7702 delegation indicator, 0xef0100 followed by a 20-byte address, counts as no contract code: the account's key still controls that address on every EVM chain. Any other code, including code of another length that starts with 0xef0100, is contract code; or
    • (b) the requirement carries a payee delegation (section 3) that is valid at B for this payTo, network, asset and origin.

The endpoint condition stops a server that is not the agent from claiming the agent's identity. The payee condition stops anyone who is not the agent from choosing where the agent's payments go.

3. Payee delegation

A seller whose payments go to an address other than its agent wallet (a treasury, a splitter, a payment processor, a wallet on another network) authorises it with an EIP-712 signature by the agent wallet:

struct PayeeDelegation {
    uint256 chainId;        // chain of the identity registry
    address registry;       // the identity registry
    uint256 agentId;
    address agentWallet;    // the agent wallet that signs, as registered when signing
    uint64  walletSetAt;    // block number of the agentWallet MetadataSet event that set agentWallet
    string  network;        // CAIP-2 network of the payment, e.g. "eip155:8453"
    string  payTo;          // the payee as the payment requirement writes it (0x hex or another network's form)
    string  asset;          // the asset as the payment requirement writes it; "*" = any asset on that network
    string  origin;         // "https://host[:port]"; "*" = every endpoint origin in the registration file
    uint64  validAfter;     // unix seconds
    uint64  validUntil;     // unix seconds; MUST be greater than validAfter
    bytes32 nonce;
}

EIP-712 domain: name = "x402 Payee Delegation", version = "2", chainId and verifyingContract = the identity registry's chain id and address.

walletSetAt is the block number of the identity registry's MetadataSet event, for this agentId and the key agentWallet, that set agentWallet as the agent wallet (the event emitted by register or by setAgentWallet). It binds the delegation to that one setting of the wallet, so that rotating the agent wallet away and back does not revive delegations signed before the rotation.

In the payment requirement, extra.erc8004.delegation is { "message": <PayeeDelegation as JSON, integers as decimal strings>, "signature": "0x…" }.

A delegation is valid at block B when:

  • the message's chainId, registry and agentId name the identity the requirement names;
  • agentWallet equals the agent wallet at B (so rotating the agent wallet revokes every delegation it signed);
  • the latest MetadataSet event for this agentId and the key agentWallet at or before B carries agentWallet and was emitted in block walletSetAt (so a wallet rotated away and back, A → B → A, does not revive what A signed before; the new setting is a new event in a later block). A checker that cannot read that event reports not-read;
  • validAfter <= t < validUntil, where t is the checker's current time, and validUntil - validAfter is at most 7,776,000 seconds (90 days);
  • network, payTo and asset equal the requirement's (payTo and asset compared case-insensitively when both are 0x hex), or asset is "*";
  • origin equals the resource's origin, or is "*";
  • the requirement's network and payTo are listed in payees of the agent's registration file as read at B (section 6). A registration file with no payees list declares no payee, so no delegation is valid against it;
  • the signature recovers to agentWallet, or, when agentWallet has contract code on the registry's chain, ERC-1271 isValidSignature on agentWallet at B returns the magic value.

A seller SHOULD keep delegations short-lived and SHOULD NOT use "*" for asset or origin when it can name them. There is no on-chain revocation list. A seller revokes one delegation by removing that payee's line from payees, which leaves its other delegations valid; how far that removal can be relied on depends on where the registration file is kept (section 6). Rotating the agent wallet revokes every delegation it signed, and stays a revocation if the same wallet is set again later. Where neither is available to the payer as a guarantee, validUntil is the only bound, which is why the ceiling is 90 days and shorter validity is RECOMMENDED.

A wallet rotated away and back within one block keeps the same walletSetAt; a checker reading only the latest event cannot tell the two apart, so such a seller has chosen to keep its delegations.

Version 1 delegations. A delegation signed under domain version "1", whose message has no walletSetAt, was the format before this field was added. Checkers SHOULD accept a version 1 delegation by every rule above except the walletSetAt rule until 2027-02-01 00:00 UTC, and MUST NOT accept it after. Sellers SHOULD re-sign as version 2.

Transition for the 90-day ceiling and the payees rule. Both rules were added on 2026-11-17. A delegation whose validAfter is earlier than 2026-11-17 00:00 UTC (unix 1794873600) was signed under the earlier rules: a ceiling of 31,536,000 seconds (365 days), and a payees list that was reported on but did not bind. Until the transition date, 2027-02-15 00:00 UTC (unix 1802649600, 90 days after the change), checkers SHOULD treat such a delegation as follows, and MUST NOT after it:

  • its validUntil - validAfter may be up to 31,536,000 seconds, so it stays valid until the earlier of its own validUntil and the transition date;
  • when the registration file has no payees list at all, it is still valid, and the checker reports payee-not-declared beside the outcome. When the file has a payees list that does not name the payee, the delegation is invalid at once: the list is the seller's own statement.

A delegation whose validAfter is 2026-11-17 00:00 UTC or later gets both rules at once. A new delegation that writes an earlier validAfter to reach the longer ceiling is, by the first rule, invalid from the transition date.

4. Verification and outcomes

A checker verifies one payment requirement against one identity, reads the registry and the registration file at one block B of the registry's chain (RECOMMENDED: the latest block the checker considers safe), and returns exactly one outcome:

OutcomeMeaning
verified-walletBound by 2(a): payTo is the agent wallet.
verified-delegationBound by 2(b): a valid delegation names this payTo.
mismatchThe identity was read, the endpoint matches, and payTo is neither the agent wallet nor covered by a valid delegation.
invalid-delegationA delegation is present but fails a rule in section 3, including a payee that is not listed in payees (the checker SHOULD say which rule).
endpoint-unlistedThe identity was read, but the resource's origin is not in its registration file.
owner-onlyThe identity has no agent wallet registered, and payTo is the identity's owner (ownerOf(agentId) at B) on the registry's chain. Not verified: an owner may be a marketplace or a cold key that does not stand behind the endpoint.
no-agent-walletThe identity has no agent wallet registered, payTo is not its owner, and no valid delegation can exist.
no-identityNo identity was named or known for this requirement.
not-readThe checker could not read the registry, the registration file, or the code at the agent wallet. It MUST NOT be reported as any other outcome.

The answer MUST also carry the identity checked, the chain id and number of B, the agent wallet read, the payTo, and, for not-read, which read failed.

A payer that supports this proposal:

  • SHOULD sign a payment only on verified-wallet or verified-delegation;
  • MUST NOT treat not-read as verified;
  • SHOULD NOT treat owner-only as verified; a seller in that state reaches verified-wallet by registering its agent wallet, which ERC-8004 lets the owner do with a signature of that wallet;
  • MUST, if its own policy pays on another outcome, record which outcome it paid on.

A facilitator MAY run the check and MAY refuse to settle a payment whose requirement is mismatch, but a payer MUST NOT rely on a facilitator's check alone when the facilitator was named by the same 402 answer it is checking.

5. Signed payment

When the payer has already signed the payment, the checker SHOULD also compare it with the requirement: the signed recipient (for ERC-3009, the authorization's to) MUST equal payTo, and the signed value MUST NOT exceed the amount asked. A difference is reported beside the outcome as payment-differs. This catches a requirement that was checked and a payment that was built from a different one.

6. Discovery

A seller lists, in its ERC-8004 registration file, under its x402 service, the payees it may use and the delegations that authorise them, so that a directory or checker can verify the seller before any payment is asked. A seller that uses a delegation MUST list the delegated payee (its network and payTo); a seller paid only at its agent wallet SHOULD list it:

{
  "services": [
    {
      "name": "x402",
      "endpoint": "https://example.com/api/thing",
      "payees": [
        { "network": "eip155:4663", "payTo": "0x…" },
        { "network": "eip155:8453", "payTo": "0x…", "delegation": { "message": { }, "signature": "0x…" } }
      ]
    }
  ]
}

The list binds delegations. A delegation is valid only for a network and payTo that appear together in one entry of payees in the file as read at B (section 3); the entry need not carry the delegation itself, which may arrive in the 402 answer. network is compared as a CAIP-2 identifier and payTo case-insensitively when both are 0x hex. A payee that is absent, an empty list, or a file with no list gives invalid-delegation. Removing one entry therefore revokes the delegation for that payee and leaves the seller's other delegations valid.

How far a removal can be relied on. Whoever controls where the registration file is served cannot forge a delegation, but can serve an earlier copy of the file in which a removed entry is still present, for as long as that delegation is unexpired. A removal is tamper-proof only when the identity's tokenURI is content-addressed (for example ipfs:// with the content identifier) or a data: URI, because then only a registry transaction by the identity's owner or an approved operator can change what the file says. For a file served over HTTPS, validUntil remains the only bound a payer can rely on. The same host can also remove entries and so stop valid payments; that fails closed.

Rule 2(a) does not depend on the list. For any outcome, a checker that reads a payees list and finds the 402's network and payTo absent from it SHOULD report payee-not-declared beside the outcome. The 402 answer remains what a payment is made against.

Rationale

  • Why the agent wallet and not the identity owner. ERC-8004 lets the owner of an identity set an agent wallet only with a signature of that wallet, so the agent wallet is the one address proven to be the agent's on chain. The owner may be a cold key, a multisig or a marketplace contract that never receives payments.
  • Why a signed delegation and not an on-chain list. Many sellers receive into a shared treasury or on several networks. An off-chain EIP-712 delegation costs nothing to issue, works for payees on networks the registry is not on, and is checked with one signature recovery. Rotating the agent wallet revokes all of them at once.
  • Why walletSetAt and not wallet equality alone. Equality with the current agent wallet revokes on rotation, but revives every unexpired delegation if the old wallet is set again. Binding the block of the setting event is a revocation epoch that needs no new contract storage: the event is already emitted, and checkers already read it.
  • Why the payees list binds a delegation. A delegation travels in every 402 answer, so anyone can keep a copy, and it verifies until validUntil. If the key to a receiving address leaks, or a payment processor is let go, whoever holds that address and can change the 402 answer presents the old delegation and is verified. Without a binding list the only remedy short of waiting is a new agent wallet setting, which voids every delegation on every network at once. With it, removing one line revokes one delegation. The cost is that a new payee needs a file update as well as a signature.
  • Why 90 days. For a registration file served over HTTPS, validUntil is the only bound a payer can rely on (section 6), so the ceiling is the longest a lost payee can keep verifying. A year was too long for that.
  • Why the EIP-7702 indicator is not contract code. Rule 2(a) accepts an agent wallet on other EVM networks because one key controls an externally owned account's address on all of them. An account that has set an EIP-7702 delegation on the registry's chain is still controlled by that key everywhere; testing only for empty code would make such a seller sign a delegation to its own address for every other network.
  • Why the endpoint condition. Without it, any server can name a well-known agent's identity, set payTo to that agent's wallet and pass the payee check while serving nothing; worse, a payer would credit that agent with the delivery. Binding the resource's origin to the registration file closes this.
  • Why fixed outcomes and no score. A payer applies its own policy; a checker's job is to say what holds. Keeping not-read separate stops a failed read from turning into a pass or a fail.
  • Why extra. x402 payment requirements already carry an extra object for scheme-specific data; using it keeps existing clients working unchanged.

Backwards Compatibility

Sellers that do not add extra.erc8004 keep working; payers that do not check are unaffected. Delegations signed as version 1 (no walletSetAt) stay valid until 2027-02-01 (section 3). A payer that checks gets no-identity for such sellers and decides by its own policy. Existing registration files without payees stay valid for sellers paid at their agent wallet (rule 2(a)). A seller that uses delegations needs a payees list: delegations signed before 2026-11-17 keep verifying without one, and with a window of up to 365 days, until 2027-02-15 (section 3); from then on the list is required and the ceiling is 90 days for every delegation.

Test Cases

The reference implementation's tests cover, among others:

  • register alone: the agent wallet set by the MetadataSet right after Registered.
  • register and setAgentWallet in one transaction, and register, transfer, setAgentWallet.
  • An onERC721Received callback that sets, unsets or transfers inside register: the latest event disagrees with storage, so the setting is not read.
  • A delegation by A with walletSetAt = the block A was set; the agent wallet rotates to B and back to A: the latest setting is a later block, so the delegation fails the walletSetAt rule (invalid-delegation).
  • The same delegation with no rotation: verified-delegation. The setting event unreadable: not-read.
  • A version 1 delegation: accepted before 2027-02-01, refused after; a version 1 signature does not verify as version 2.
  • The 90-day ceiling: a delegation of exactly 90 days is valid, one of 90 days and one second is not; a delegation signed before 2026-11-17 with 365 days is valid one second before 2027-02-15 00:00 UTC and invalid at it.
  • The payees list: a listed payee is valid; a list that does not name the payee, or names its payTo for another network, is invalid-delegation; no list at all is valid with payee-not-declared for a delegation signed before 2026-11-17 until 2027-02-15, and invalid-delegation for a new one and for any delegation from that date.
  • EIP-7702: an agent wallet whose code on the registry's chain is exactly the 23-byte indicator is verified-wallet on another EVM network; 24 bytes starting with 0xef0100 are contract code (mismatch without a delegation).

The last three groups are given as thirteen complete vectors (registration file, agent wallet code, requirement, signed delegation, checker time and expected outcome) in review-2026-11-vectors.json.

The registration, batched-transaction and onERC721Received cases were found and first run against the registry's source by it44 in the discussion thread, and the A → B → A case by SergeevDmitry. The binding payees list, the lower validity ceiling and the EIP-7702 case were proposed by Douglas Borthwick in the discussion thread, from running an x402 seller on several networks.

Reference Implementation

Toll (ERC-8004 agent 20030 on Robinhood Chain) runs this check as part of its pre-sign check: a caller sends the 402's payment requirement, optionally the agentId and the signed payment, and receives the payee outcome with the block read. Its agent census reads every registered agent's registration file and 402 daily, and publishes per-agent results. The reference code will be linked here once the reference contract-free checker is extracted into a standalone library.

Security Considerations

  • The registry chain is the trust root. A checker MUST read the identity registry from a node it trusts; a lying RPC can return any agent wallet.
  • Registration file hosting. The registration file is fetched over HTTP or IPFS. An attacker who controls the file's host can list its own origin as an endpoint, but cannot change the agent wallet or forge a delegation, so it can at most redirect where a resource is served, not where payment goes. It can, however, undo a revocation: by serving a copy of the file in which a removed payees entry is present again, it keeps that payee's unexpired delegation verifying. Only a content-addressed or data: tokenURI makes a removal final (section 6); otherwise the 90-day ceiling bounds it. A payer that needs more SHOULD prefer sellers whose tokenURI is content-addressed.
  • A lost payee. If a receiving address is lost or a processor is let go while its delegation is unexpired, the seller removes that entry from payees. Where the file's host is not trusted to keep it removed, the seller sets a new agent wallet, which voids every delegation.
  • Externally owned accounts across chains. Rule 2(a) accepts the agent wallet on another EVM network only when it has no contract code on the registry's chain, or exactly the EIP-7702 delegation indicator. A contract wallet at the same address on another chain may be controlled by someone else, so such payees need a delegation. The indicator is matched exactly (23 bytes): code that merely begins with 0xef0100 is treated as contract code.
  • Key compromise. If the agent wallet key is compromised, the attacker can sign delegations to its own address. The remedy is the ERC-8004 owner setting a new agent wallet, which voids every earlier delegation, including when the old wallet is set again later (walletSetAt).
  • Lookalike addresses. Comparison is on the full address, never on a prefix or suffix. Checkers that echo addresses to a person SHOULD show them in full.
  • Untrusted text. Agent names and descriptions in registration files are written by the seller and MAY carry instructions aimed at an agent reading them; checkers and payers MUST treat them as data.

Copyright and related rights waived via CC0.

EIP.tools

EIP.tools

Search, read, and map Ethereum improvement proposals, ERCs, RIPs, and CAIPs from one focused interface.

Farcaster
by @apoorveth