x402-chainlink

What is it?
x402-chainlink is a comprehensive, self-custodian (user controls the funds) payment SDK and smart contract suite that functions as a decentralized "Stripe for Web3". At its core, it is a developer toolkit designed to bridge standard web protocols with blockchain settlement, specifically tailored for the rising "Agentic Economy". It is a developer toolkit that enables the seamless monetization of APIs, digital resources, and AI agent workflows using standard HTTP 402 (Payment Required) protocol. The entire system is secured by the Chainlink Runtime Environment (CRE), allowing for decentralized, trustless verification and settlement. It is designed to caters the "Agentic Economy" by supporting Machine-to-Machine (M2M) payments, allowing headless clients and AI agents to autonomously request and pay for premium resources.

What problem does it solve?
x402-chainlink addresses the fundamental friction points that prevent Web3 payments from achieving the seamless usability of Web2 systems like Stripe, while simultaneously bridging the gap for the emerging AI economy (Check out the demo example here: https://github.com/startup-dreamer/x402-chainlink/tree/master?tab=readme-ov-file#ai-agentbackend-workflow-example) The problems that this project solves are:

• Friction in Web3 Monetization: Monetizing Web3 APIs typically forces developers to either build a centralized database to track user deposits or forces end-users to sign clunky, expensive on-chain transactions for every single API call.
• Eliminates Centralized Middlemen: Instead of relying on a centralized payment processor or restrictive escrow contracts, the protocol allows users to maintain absolute custody of their funds.
• Gasless User Experience: It solves the UX hurdle of paying network gas fees by utilizing EIP-2612 token permits, which eliminates the need for users to execute separate, expensive "Approve" transactions.
• Interoperability: It solves the need for heavy local RPC infrastructure, as the Chainlink CRE inherently observes multiple networks (Polygon, Base, Ethereum, etc.) to verify payments chain-agnostically.

How does it work?
The SDK abstracts the complexities of EIP-712 signatures, EIP-2612 permits, and smart contract execution into a fast, four-phase sequence based on the standard HTTP request-response cycle (see this diagram for detailed flow: https://github.com/startup-dreamer/x402-chainlink/tree/master?tab=readme-ov-file#architecture--protocol-flow):

• Discovery & Payment Request: A client (or AI agent) attempts to fetch a protected API resource. The API server intercepts this and responds with an HTTP 402 Payment Required status, attaching the specific payment requirements in the headers.
• Payment Authorization: The client decodes these requirements. The user's wallet (or the AI agent's funded hot wallet) generates an off-chain cryptographic signature using EIP-712 to authorize the payment intent, alongside an optional EIP-2612 signature for gasless token approval.
• Verification & Settlement via Chainlink CRE: The client retries the API request, including the signed payload in a PAYMENT-SIGNATURE header. The API forwards this payload to the Chainlink CRE.
  • Off-chain: The CRE trustlessly verifies the EIP-712 signature and checks the user's token balance.
  • On-chain: The Chainlink node broadcasts a settlement report to the X402Facilitator smart contract, which executes the immutable token transfer from the payer to the recipient.
• Secure Resource Delivery: Once the CRE confirms the successful transaction, it returns a workflow response to the API. The API then returns a 200 OK status and delivers the premium data/resource to the client.

I have wrote a detailed readme as well explaining everything here: https://github.com/startup-dreamer/x402-chainlink/

x402-Chainlink is architected as a decentralized micro-monetization protocol designed to bridge standard web communication with trustless on-chain settlement. The core design philosophy was to shift the heavy lifting of payment verification off-chain while maintaining strict cryptographic guarantees. To achieve this, I built the protocol's execution layer entirely around the Chainlink Runtime Environment (CRE).
You can go through the detailed typedoc documentation of the sdk here: https://startup-dreamer.github.io/x402-chainlink/

Here is a technical breakdown of the system layers:

1. The HTTP-to-Web3 Negotiation Layer At the top level, the system automates payment negotiations using the HTTP 402 (Payment Required) status code.

• Discovery: When an AI agent or client requests a gated resource, the server denies access and returns a 402 status. It attaches a custom PAYMENT-REQUIRED header containing the cost, accepted token, and destination chain (Ideally in future releases I want to remove the destination chain and make it truly chain agnostic utilising the full capabilites of cre).
• Off-Chain Authorization: Our TypeScript SDK automatically intercepts this response, parses the requirements, and generates an EIP-712 typed data signature. This allows the user (or an autonomous AI agent) to cryptographically authorize the payment off-chain, keeping full custody of their funds until the exact moment of settlement.

2. Verifiable Off-Chain Execution (Chainlink CRE) The Chainlink Runtime Environment serves as the "brain" of the protocol, functioning as a decentralised backend. I developed a custom CRE workflow (compiled to WebAssembly) that handles the critical state logic:

• Intent Verification: The CRE workflow receives the payment payload and signature, which then verifies the EIP-712 intent to ensure it hasn't been tampered with.
• Real-Time State Validation: The workflow executes real-time RPC calls to the target blockchain (using viem) to verify that the payer has sufficient token balances and allowances before initiating any transactions.
• Consensus & Delivery (Simulation vs. Production): In a live production environment, once validated, the Chainlink DON (Decentralized Oracle Network) reaches consensus on the payload and securely routes a settlement report to the destination chain via Chainlink Keystone. However, because live CRE deployments are not yet publicly available, our SDK explicitly utilizes a custom Simulation Mode (check out: https://github.com/startup-dreamer/x402-chainlink/tree/master?tab=readme-ov-file#prerequisites). Under the hood, the SDK programmatically wraps the Chainlink cre workflow simulate CLI. It spawns a localized CRE simulation that perfectly mimics the DON's consensus and execution process, allowing for seamless local testing and hackathon validation while remaining entirely production-ready (I am fully committed to natively integrating live DON support once released. I intend to actively maintain the SDK, expand its feature set, and keep the entire repository open-source to empower the broader developer community).

3. Smart Contract Settlement (X402Facilitator.sol) The on-chain settlement is handled by a optimized smart contract.

• Keystone Integration: The contract implements the Keystone interface. It securely processes payments by accepting settlement reports from the authorized KeystoneForwarder address, ensuring the correct report destination securely.
• Gas-Optimized 1-Click UX: I integrated EIP-2612 (Permit) functionality. Instead of requiring users to send separate, gas-heavy approve() and transferFrom() transactions, the contract processes a single off-chain signature to handle the approval and transfer in one atomic execution.
• Replay Protection: The contract enforces a strict nonce mapping architecture to guarantee that intercepted payment signatures can never be reused.

4. The Developer SDK & Agent Tooling To ensure the protocol is "Stripe-simple" for Web3 developers, I packaged the logic into a robust npm package (https://www.npmjs.com/package/x402-chainlink).

• Modular Clients: It exposes dedicated clients (DiscoveryClient, CREFacilitatorClient) for handling M2M (machine-to-machine) negotiations.
• Extensibility: The SDK features an ExtensionRegistry with strict JSON schema validation, allowing developers to easily append custom data to the EIP-712 signatures for future use cases like metered billing, subscriptions, or dynamic tipping etc.