Consensus x402 ICP Facilitator is live + Servers and Client libraries published!

Developers
1

Hello Everyone,

For the past several months I have been building Consensus Protocol a decentralized x402 Proxy and WebSocket service. I have now created and actively host a facilitator supporting the Internet Computer designed to allow servers to monetise HTTP resources and clients to pay for them programmatically.

This enables a simple model:

Clients can programmatically pay for APIs or resources using ICP tokens.

The facilitator handles verification and settlement, while the server only needs to define its pricing.

Install the ICP x402 Library

npm install @canister-software/x402-icp

This package provides ICP support for the x402 ecosystem.

It includes:

  • ExactIcpScheme — ICP settlement scheme
  • createIcpPaymentRequirements — helper for building payment requirements
  • client utilities for automatic payment

Server — Monetise an Endpoint

Before protecting a route, a server needs two things:

  1. A recipient principal (payTo) that receives payment
  2. A supported ICP asset/network registered with the x402 resource server

Example: accepting ckUSDC payments

import 'dotenv/config'
import express from 'express'
import { paymentMiddleware, x402ResourceServer } from '@x402/express'
import { HTTPFacilitatorClient } from '@x402/core/server'
import { ExactIcpScheme } from '@canister-software/x402-icp/server'

const facilitatorClient = new HTTPFacilitatorClient({
  url: 'https://facilitator.consensus.canister.software'
})

const x402Server = new x402ResourceServer(facilitatorClient)
  .register('icp:1:xevnm-gaaaa-aaaar-qafnq-cai', new ExactIcpScheme()) // ckUSDC

const app = express()
app.use(express.json())

app.use(
  paymentMiddleware(
    {
      'GET /api/data': {
        accepts: [{
          scheme: 'exact',
          price: '1000000', // 1 ckUSDC (6 decimals)
          network: 'icp:1:xevnm-gaaaa-aaaar-qafnq-cai',
          payTo: 'your-principal-id',
        }],
        description: 'Premium data endpoint',
        mimeType: 'application/json',
      },
    },
    x402Server,
  )
)

app.get('/api/data', (_req, res) => {
  res.json({ message: 'Here is your premium data!' })
})

Server Payment Flow

When a protected endpoint is accessed:

  1. Client requests a paid endpoint
  2. Server responds with 402 Payment Required
  3. The response contains ICP payment requirements
  4. Client performs icrc2_approve
  5. Client signs the request with its cryptographic identity
  6. Facilitator verifies the payment and executes icrc2_transfer_from
  7. Server returns the protected resource

This allows servers to monetise APIs with minimal infrastructure.

Creating ICP Payment Requirements

You can construct requirements directly:

import { createIcpPaymentRequirements } from '@canister-software/x402-icp/server'

const requirements = createIcpPaymentRequirements({
  amount: '1000000',
  network: 'icp:1:xevnm-gaaaa-aaaar-qafnq-cai',
  payTo: 'your-principal-id',
})

This produces an x402 payment requirement describing:

  • payment scheme
  • token network
  • amount
  • recipient principal

When used with a facilitator, additional settlement metadata is injected automatically.

Client — Automatic Payment

The client library automatically handles the payment flow.

Client Flow

  1. Client requests a paid endpoint
  2. Server returns 402
  3. Client performs icrc2_approve
  4. Client signs the payment authorization
  5. Request is retried automatically
  6. Facilitator settles the payment
  7. Response is returned

Example Client

import 'dotenv/config'
import { x402Client } from '@x402/core/client'
import { wrapFetchWithPayment } from '@x402/fetch'
import { registerExactIcpScheme, pemToSigner } from '@canister-software/x402-icp/client'

// Load identity from dfx PEM — this principal must hold the payment token
const signer = await pemToSigner('./identity.pem')
console.log(`Paying from: ${signer.principal}`)

const client = new x402Client()
registerExactIcpScheme(client, { signer })

const fetchWithPayment = wrapFetchWithPayment(fetch, client)

const response = await fetchWithPayment('https://your-server.com/api/data')
const data = await response.json()

console.log(data)

Any valid identity works:

  • Ed25519
  • Secp256k1

The identity must hold the payment token.

Export from dfx:

dfx identity export <name>

ps: I have not tried the new dfx cli yet

Facilitator

The facilitator verifies payments and executes settlement.

Supported networks are listed here:

https://facilitator.canister.software/supported

Links

GitHub
https://github.com/Canister-Software/x402-icp

Facilitator
https://facilitator.canister.software/info

Consensus Protocol
https://forum.dfinity.org/t/consensus-protocol-is-live-x402-proxy-and-websocket-service/64526

If you’re building paid APIs, AI endpoints, data feeds, or premium services on ICP, this enables native programmable payments using ICRC tokens.

Feedback is welcome! Please share any idea or concerns !

7 Likes