x402/specs/extensions/builder_code.md
Cloud 1e0434b18e
docs: add builder_code.md spec (#2050)
* docs: add builder_code.md spec

* support services array
2026-05-04 14:18:52 -04:00

10 KiB

Extension: builder-code

Summary

The builder-code extension enables on-chain attribution tracking for x402 payments by appending ERC-8021 Schema 2 builder codes to settlement transaction calldata. It attributes which application exposed the paid endpoint and which facilitator settled the payment.

This extension implements Schema 2 (CBOR-encoded) of ERC-8021. The m (custom metadata) and r (custom registries) fields are not supported.


ERC-8021 Schema 2 Overview

ERC-8021 defines a structured data suffix appended to transaction calldata for entity attribution. Schema 2 uses CBOR encoding for extensibility.

Suffix Format

The complete suffix appended to calldata is (ordered end of calldata backwards):

Component Size Description
ercMarker 16 bytes Constant identifier: 80218021802180218021802180218021
schemaId 1 byte 0x02 for Schema 2
cborLength 2 bytes Length of CBOR data (big-endian)
cborData variable CBOR-encoded map of attribution fields

Wire order: [cborData][cborLength (2B)][schemaId (1B)][ercMarker (16B)]

CBOR Map Fields

Key Type Description
a string App code — the application that exposed the paid endpoint
w string Wallet code — the facilitator that settled the payment on-chain
s array of string Service codes — clients and intermediaries that participated

All fields are optional.

Builder Code Format

Codes must match the pattern ^[a-z0-9_]{1,32}$:

  • Length: 1-32 characters
  • Characters: lowercase alphanumeric and underscores only

PaymentRequired

The application declares its builder code per-route in the payment middleware configuration.

{
  "x402Version": 2,
  "error": "Payment required",
  "accepts": [ ... ],
  "extensions": {
    "builder-code": {
      "info": {
        "a": "my_app"
      },
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "a": {
            "type": "string",
            "pattern": "^[a-z0-9_]{1,32}$",
            "description": "App builder code"
          },
          "w": {
            "type": "string",
            "pattern": "^[a-z0-9_]{1,32}$",
            "description": "Wallet builder code"
          },
          "s": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[a-z0-9_]{1,32}$"
            },
            "description": "Service builder codes"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

PaymentPayload

The client echoes the builder code extension from PaymentRequired into its PaymentPayload, and may append its own code(s) to the s array.

{
  "extensions": {
    "builder-code": {
      "a": "my_app",
      "s": ["my_client"]
    }
  }
}

The w (wallet) field is not set by the client. It is added by the facilitator at settlement time.


Builder Code Fields

Field Set by When Description
a Application Per-route middleware configuration Identifies the application exposing the paid endpoint
w Facilitator Settlement Identifies the facilitator settling the payment on-chain
s Client Payment payload construction Identifies the client(s) and intermediaries that participated

Facilitator Behavior

When a facilitator settles a payment containing the builder-code extension, it:

  1. Verifies that PaymentPayload.extensions["builder-code"].a matches PaymentRequired.extensions["builder-code"].info.a
  2. Reads a (app code) and s (service codes) from the payment payload extensions
  3. Adds its own builder code as the w (wallet) field
  4. Encodes the combined data as an ERC-8021 Schema 2 CBOR suffix
  5. Appends the suffix to the settlement transaction calldata

The facilitator's builder code is configured at initialization and validated against the same ^[a-z0-9_]{1,32}$ pattern.

Calldata Suffix Construction

The facilitator builds the suffix as follows:

  1. CBOR-encode a map containing all present fields (a, s, w)
  2. Compute cborLength as the byte length of the CBOR data (2 bytes, big-endian)
  3. Append: [cborData][cborLength][0x02][80218021802180218021802180218021]
  4. Return the hex-encoded result for the settlement mechanism to append to calldata

Protocol Flow

Client (App)                   Resource Server                Facilitator
      |                              |                              |
  1.  |--- request ----------------->|                              |
      |                              |                              |
  2.  |<-- 402 PaymentRequired ------|                              |
      |   extensions.builder-code:   |                              |
      |     { a: "my_app" }         |                              |
      |                              |                              |
  3.  | (sign payment, echo extensions)                             |
      |                              |                              |
  4.  |--- request + payment ------->|                              |
      |   extensions.builder-code:   |                              |
      |     { a: "my_app",          |                              |
      |       s: ["my_client"] }    |                              |
      |                              |                              |
  5.  |                              |--- verify/settle ----------->|
      |                              |   extensions.builder-code:   |
      |                              |     { a: "my_app",          |
      |                              |       s: ["my_client"] }    |
      |                              |                              |
  6.  |                              |         Facilitator adds w,  |
      |                              |         encodes CBOR suffix, |
      |                              |         appends to calldata: |
      |                              |         [cbor({a:"my_app",   |
      |                              |          s:["my_client"],    |
      |                              |          w:"my_fac"})]       |
      |                              |         [cborLen][0x02][mark] |
      |                              |                              |
  7.  |<-- 200 OK + resource data ---|                              |
      |                              |                              |

Examples

Single App Attribution

Application declares its builder code:

{
  "extensions": {
    "builder-code": {
      "info": {
        "a": "bc_myapp"
      },
      "schema": { ... }
    }
  }
}

Settlement calldata suffix (hex):

{original_calldata} a161616862635f6d79617070 000c 02 80218021802180218021802180218021

Decoded:

  • CBOR: {"a": "bc_myapp"}
  • cborLength: 0x000c (12 bytes)
  • schemaId: 0x02
  • marker: 80218021802180218021802180218021

App + Facilitator Attribution

After facilitator adds its w code at settlement:

{original_calldata} a261616862635f6d7961707061777062635f6d79666163696c697461746f72 001f 02 80218021802180218021802180218021

Decoded:

  • CBOR: {"a": "bc_myapp", "w": "bc_myfacilitator"}
  • cborLength: 0x001f (31 bytes)
  • schemaId: 0x02
  • marker: 80218021802180218021802180218021

Validation

Builder Code Validation

All builder codes (a, w, and each entry in s) must:

  • Match ^[a-z0-9_]{1,32}$
  • Be 1-32 characters long
  • Contain only lowercase letters, digits, and underscores

Invalid codes must be rejected at declaration time (application) and at construction time (facilitator). The facilitator validates each entry in s for format only — s is client self-reported and cannot be verified against any authoritative source.

App Code Echo Validation

The facilitator MUST verify that the a field echoed by the client in PaymentPayload.extensions["builder-code"] exactly matches the a field declared by the application in PaymentRequired.extensions["builder-code"].info. A mismatch indicates the client tampered with the attribution and the payment MUST be rejected.

Schema Validation

The schema field uses JSON Schema Draft 2020-12. Facilitators should validate info against the provided schema.


Parsing

Off-chain parsers can extract builder code attribution from settlement calldata using the ERC-8021 parsing algorithm:

  1. Extract the last 16 bytes and verify they match the ERC-8021 marker (80218021...)
  2. Extract the preceding byte as schemaId and verify it equals 0x02
  3. Extract the preceding 2 bytes as cborLength (big-endian)
  4. Extract the preceding cborLength bytes as cborData
  5. Decode cborData as a CBOR map
  6. Read a (app code), w (wallet code), and s (service codes array) from the map

Responsibilities

Role Responsibility
Application Declares a (app code) per-route in the payment middleware configuration
Client Echoes a from PaymentRequired; optionally populates s with its own service code(s) in PaymentPayload
Facilitator Adds w (wallet code) at settlement, encodes the full CBOR suffix (a, s, w), appends to calldata