x402-base-pulse

PaulieB14

This is not the latest version — go to v3.3.0

v3.0.0/94 downloads/Repository

Package ref

x402-base-pulse@v3.0.0

Download .spkg

Run package

CLI

Run db_out from the command line.

substreams run x402-base-pulse@v3.0.0 db_out -e base

Authenticate by running substreams auth or directly on thegraph.market (see docs).

README

x402 Base Pulse

Real-time payment protocol analytics for Coinbase x402 on Base

Track every x402 payment settlement on Base. This Substreams detects when facilitators call transferWithAuthorization on USDC to settle HTTP 402 payments, extracting payer, recipient, amount, and facilitator data from each settlement.

v3.0.0 — Now gates EIP-3009 settlements through the on-chain FacilitatorRegistry, matching the x402-subgraph. Facilitator names, URLs, and active status are resolved from registry events.

How It Works

The x402 protocol enables internet-native payments using the HTTP 402 status code. When a client wants to access a paid resource:

Server responds with HTTP 402 + payment requirements
Client signs an EIP-3009 authorization
Facilitator calls transferWithAuthorization on USDC to settle payment on-chain
USDC emits AuthorizationUsed + Transfer events
This Substreams captures those events and extracts settlement data
FacilitatorRegistry gates EIP-3009 settlements — only registered facilitators are indexed

Modules

Module	Kind	Description
`map_facilitator_registry_events`	Map	Extracts `FacilitatorAdded` / `FacilitatorRemoved` events from the on-chain registry
`store_facilitator_registry`	Store	Maintains the set of registered facilitators with names and URLs
`map_x402_settlements`	Map	Pairs `AuthorizationUsed` + `Transfer` events, gated by facilitator registry
`store_payer_volume`	Store	Accumulates total USDC spent per payer
`store_payer_count`	Store	Counts payments per payer
`store_recipient_volume`	Store	Accumulates total USDC received per resource server
`store_recipient_count`	Store	Counts payments per recipient
`store_facilitator_volume`	Store	Accumulates total USDC volume per facilitator
`store_facilitator_count`	Store	Counts settlements per facilitator
`store_facilitator_gas`	Store	Tracks gas costs per facilitator
`store_first_seen`	Store	Records first-seen timestamp per payer, recipient, and facilitator
`map_payer_stats`	Map	Computes payer leaderboards and averages
`map_recipient_stats`	Map	Computes resource server revenue stats
`map_facilitator_stats`	Map	Computes facilitator economics with name, URL, and active status from registry
`db_out`	Map	Outputs `DatabaseChanges` for PostgreSQL sink

Contracts Indexed

Contract	Address	Events
USDC (Base)	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`	`AuthorizationUsed`, `Transfer`
FacilitatorRegistry	`0x67C75c4FD5BbbF5f6286A1874fe2d7dF0024Ebe8`	`FacilitatorAdded`, `FacilitatorRemoved`
x402ExactPermit2Proxy	`0x4020615294c913F045dc10f0a5cdEbd86c280001`	`Settled`, `SettledWithPermit`
x402UptoPermit2Proxy	`0x4020633461b2895a48930Ff97eE8fCdE8E520002`	`Settled`, `SettledWithPermit`

Quick Start

# Stream settlements
substreams run x402-base-pulse map_x402_settlements \
  -e base-mainnet.streamingfast.io:443 \
  -s 29000000 -t +1000

# GUI mode
substreams gui x402-base-pulse map_x402_settlements \
  -e base-mainnet.streamingfast.io:443 \
  -s 29000000

# Sink to PostgreSQL
substreams-sink-sql run "psql://localhost/x402" \
  x402-base-pulse-v3.0.0.spkg \
  -e base-mainnet.streamingfast.io:443

SQL Output

Tables

Table	Key	Description
`settlements`	`tx_hash-log_index`	Every settlement with payer, recipient, amount, facilitator, gas
`payers`	`payer_address`	Aggregated spend and payment count per payer
`recipients`	`recipient_address`	Revenue and payment count per resource server
`facilitators`	`facilitator_address`	Name, URL, active status, volume settled, settlement count, total gas spent

Views

View	Description
`daily_stats`	Daily protocol-wide volume, unique participants, gas
`top_payers`	Ranked by total USDC spent
`top_recipients`	Ranked by total USDC received
`facilitator_economics`	Name, active status, volume settled vs gas cost per facilitator
`whale_payments`	Payments > $100 USDC
`recent_settlements`	Latest 100 settlements

Build

cargo build --target wasm32-unknown-unknown --release
substreams pack substreams.yaml

References

x402 Protocol -- Coinbase's HTTP 402 payment standard
How It Works -- Settlement flow
Network Support -- Supported tokens and chains
EIP-3009 -- Transfer With Authorization
x402 Source -- Protocol implementation
x402-subgraph -- Companion subgraph with matching facilitator gating

Network

Chain: Base
Start Block: 25,000,000 (settlements), 30,011,612 (FacilitatorRegistry)
Endpoint: base-mainnet.streamingfast.io:443

Modules

Execution graph

17 modules

mapMain

db_out

Outputs database changes for PostgreSQL sink. Tables: settlements, payers, recipients, facilitators

from #25000000

Output

sf.substreams.sink.database.v1.DatabaseChanges

Inputs

paramsmap_x402_settlements map_payer_stats map_recipient_stats map_facilitator_stats

map

map_facilitator_registry_events

Extracts FacilitatorAdded and FacilitatorRemoved events from the on-chain FacilitatorRegistry contract. These events define which addresses are authorized x402 facilitators.

from #30011612

Output

x402.v1.FacilitatorRegistryEvents

Inputs

sf.ethereum.type.v2.Block

map

map_facilitator_stats

Computes facilitator economics: volume processed, gas spent, settlement count. Enriches with name and active status from the FacilitatorRegistry.

from #25000000

Output

x402.v1.FacilitatorStats

Inputs

map_x402_settlements store_facilitator_volume store_facilitator_count store_facilitator_gas store_first_seen store_facilitator_registry

map

map_payer_stats

Computes real-time payer statistics by combining settlement data with accumulated store values.

from #25000000

Output

x402.v1.PayerStats

Inputs

map_x402_settlements store_payer_volume store_payer_count store_first_seen

map

map_recipient_stats

Computes real-time recipient (resource server) revenue statistics.

from #25000000

Output

x402.v1.RecipientStats

Inputs

map_x402_settlements store_recipient_volume store_recipient_count store_first_seen

map

map_x402_settlements

Extracts x402 payment settlements on Base by detecting EIP-3009 AuthorizationUsed events on the USDC contract. Filters EIP-3009 settlements to only include transactions where tx.from is a registered facilitator in the on-chain FacilitatorRegistry. Permit2 proxy settlements are self-identifying and not gated.

from #25000000

Output

x402.v1.Settlements

Inputs

sf.ethereum.type.v2.Block store_facilitator_registry

store

store_facilitator_count

Counts total settlements per facilitator. Key: {facilitator_address}

from #25000000

Store value

int64

Update policy

add

Inputs

map_x402_settlements

store

store_facilitator_gas

Accumulates total gas spent per facilitator. Key: {facilitator_address}

from #25000000

Store value

bigint

Update policy

add

Inputs

map_x402_settlements

store

store_facilitator_registry

Maintains the set of registered facilitators with their names. Key: facilitator address (lowercase). Value: "name|url" or empty if removed. Uses set policy — FacilitatorRemoved overwrites with empty string.

from #30011612

Store value

string

Update policy

set

Inputs

map_facilitator_registry_events

store

store_facilitator_volume

Accumulates total volume settled per facilitator. Key: {facilitator_address}

from #25000000

Store value

bigint

Update policy

add

Inputs

map_x402_settlements

store

store_first_seen

Records first-seen block timestamp per entity. Key: payer:{addr}, recipient:{addr}, facilitator:{addr}

from #25000000

Store value

int64

Update policy

set_if_not_exists

Inputs

map_x402_settlements

store

store_payer_count

Counts total payments per payer address. Key: {payer_address}

from #25000000

Store value

int64

Update policy

add

Inputs

map_x402_settlements

store

store_payer_volume

Accumulates total payment volume per payer address. Key: {payer_address}

from #25000000

Store value

bigint

Update policy

add

Inputs

map_x402_settlements

store

store_recipient_count

Counts total payments per recipient. Key: {recipient_address}

from #25000000

Store value

int64

Update policy

add

Inputs

map_x402_settlements

store

store_recipient_volume

Accumulates total revenue per recipient (resource server). Key: {recipient_address}

from #25000000

Store value

bigint

Update policy

add

Inputs

map_x402_settlements

Show 2 dependencies

map

ethcommon:all_events

`all_events` gives you all the events in a block (from successful transactions), with basic block hash/number/timestamp and transaction hash

Output

sf.substreams.ethereum.v1.Events

Inputs

sf.ethereum.type.v2.Block

blockIndex

ethcommon:index_events

`index_events` sets the following keys on the block: * Event signatures evt_sig:0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef (signature in hex, prefixed by 0x) * Event address evt_addr:0x0123456789abcdef0123456789abcdef01234567 (address in hex, prefixed by 0x)

Output

sf.substreams.index.v1.Keys

Inputs

ethcommon:all_events

Protobuf

x402.v1

FacilitatorRegistryEventsmain

x402.v1.FacilitatorRegistryEvents

FacilitatorRegistry events detected in a block

FacilitatorRegistryEvent[]events = 1

uint64block_number = 2

FacilitatorStatsmain

x402.v1.FacilitatorStats

Facilitator gas economics

FacilitatorStat[]stats = 1

uint64block_number = 2

PayerStatsmain

x402.v1.PayerStats

Aggregated payer statistics

PayerStat[]stats = 1

uint64block_number = 2

RecipientStatsmain

x402.v1.RecipientStats

Aggregated recipient (resource server) statistics

RecipientStat[]stats = 1

uint64block_number = 2

Settlementsmain

x402.v1.Settlements

All x402 settlements detected in a block

Settlement[]settlements = 1

uint64block_number = 2

Timestampblock_timestamp = 3

FacilitatorRegistryEvent

x402.v1.FacilitatorRegistryEvent

stringfacilitator_address = 1

stringname = 2

stringurl = 3

boolis_added = 4

true = added, false = removed

FacilitatorStat

x402.v1.FacilitatorStat

stringfacilitator_address = 1

uint64total_settlements = 2

stringtotal_volume_settled = 3

Total USDC volume processed

stringtotal_gas_spent = 4

Total gas cost in wei

Timestampfirst_settlement_at = 5

Timestamplast_settlement_at = 6

stringname = 7

From FacilitatorRegistry FacilitatorAdded event

boolis_active = 8

False if FacilitatorRemoved was emitted

stringurl = 9

Facilitator endpoint URL

PayerStat

x402.v1.PayerStat

stringpayer_address = 1

stringtotal_spent = 2

Total USDC spent

uint64total_payments = 3

Timestampfirst_payment_at = 4

Timestamplast_payment_at = 5

RecipientStat

x402.v1.RecipientStat

stringrecipient_address = 1

stringtotal_received = 2

Total USDC received

uint64total_payments = 3

Timestampfirst_payment_at = 4

Timestamplast_payment_at = 5

Settlement

x402.v1.Settlement

A single x402 payment settlement

Detected via two mechanisms per the x402 protocol (https://docs.cdp.coinbase.com/x402/core-concepts/how-it-works):

EIP-3009: AuthorizationUsed events on USDC from facilitator calling transferWithAuthorization. The nonce field is populated.
Permit2 proxy: Settled/SettledWithPermit events from the x402ExactPermit2Proxy contract (when deployed on mainnet).

stringid = 1

tx_hash-log_index

stringtx_hash = 2

uint32log_index = 3

uint64block_number = 4

Timestamptimestamp = 5

stringpayer = 6

Payment details

stringrecipient = 7

Resource server (payTo)

stringtoken = 8

Token address (USDC)

stringamount = 9

Payment amount (atomic units, 6 decimals for USDC)

stringsettlement_type = 10

Settlement classification

stringfacilitator = 11

Facilitator info (who submitted tx and paid gas)

stringgas_used = 12

Gas consumed by the transaction

stringgas_price = 13

Effective gas price (wei)

stringnonce = 14

EIP-3009 authorization nonce (from AuthorizationUsed event)

Show 14 dependencies

sf.ethereum.substreams.v1

RpcCall

sf.ethereum.substreams.v1.RpcCall

bytesto_addr = 1

bytesdata = 2

RpcCalls

sf.ethereum.substreams.v1.RpcCalls

RpcCall[]calls = 1

RpcResponse

sf.ethereum.substreams.v1.RpcResponse

bytesraw = 1

boolfailed = 2

RpcResponses

sf.ethereum.substreams.v1.RpcResponses

RpcResponse[]responses = 1

sf.ethereum.type.v2

BlockRef

sf.ethereum.type.v2.BlockRef

byteshash = 1

uint64number = 2

BlockWithRefs

sf.ethereum.type.v2.BlockWithRefs

BlockWithRefs is a lightweight block, with traces and transactions purged from the block within, and only. It is used in transports to pass block data around.

stringid = 1

Blockblock = 2

TransactionRefstransaction_trace_refs = 3

boolirreversible = 4

HeaderOnlyBlock

sf.ethereum.type.v2.HeaderOnlyBlock

HeaderOnlyBlock is used to optimally unpack the [Block] structure (note the corresponding message number for the header field) while consuming less memory, when only the header is desired.

WARN: this is a client-side optimization pattern and should be moved in the consuming code.

BlockHeaderheader = 5

TransactionRefs

sf.ethereum.type.v2.TransactionRefs

bytes[]hashes = 1

TransactionTraceWithBlockRef

sf.ethereum.type.v2.TransactionTraceWithBlockRef

TransactionTracetrace = 1

BlockRefblock_ref = 2

Reasonenum

sf.ethereum.type.v2.BalanceChange.Reason

REASON_UNKNOWN = 0

REASON_REWARD_MINE_UNCLE = 1

REASON_REWARD_MINE_BLOCK = 2

REASON_DAO_REFUND_CONTRACT = 3

REASON_DAO_ADJUST_BALANCE = 4

REASON_TRANSFER = 5

REASON_GENESIS_BALANCE = 6

REASON_GAS_BUY = 7

REASON_REWARD_TRANSACTION_FEE = 8

REASON_REWARD_FEE_RESET = 14

REASON_GAS_REFUND = 9

REASON_TOUCH_ACCOUNT = 10

REASON_SUICIDE_REFUND = 11

REASON_SUICIDE_WITHDRAW = 13

REASON_CALL_BALANCE_OVERRIDE = 12

REASON_BURN = 15

Used on chain(s) where some Ether burning happens

REASON_WITHDRAWAL = 16

CallTypeenum

sf.ethereum.type.v2.CallType

UNSPECIFIED = 0

CALL = 1

direct? what's the name for Call alone?

CALLCODE = 2

DELEGATE = 3

STATIC = 4

CREATE = 5

create2 ? any other form of calls?

Reasonenum

sf.ethereum.type.v2.GasChange.Reason

REASON_UNKNOWN = 0

REASON_CALL = 1

REASON_CALL_CODE = 2

REASON_CALL_DATA_COPY = 3

REASON_CODE_COPY = 4

REASON_CODE_STORAGE = 5

REASON_CONTRACT_CREATION = 6

REASON_CONTRACT_CREATION2 = 7

REASON_DELEGATE_CALL = 8

REASON_EVENT_LOG = 9

REASON_EXT_CODE_COPY = 10

REASON_FAILED_EXECUTION = 11

REASON_INTRINSIC_GAS = 12

REASON_PRECOMPILED_CONTRACT = 13

REASON_REFUND_AFTER_EXECUTION = 14

REASON_RETURN = 15

REASON_RETURN_DATA_COPY = 16

REASON_REVERT = 17

REASON_SELF_DESTRUCT = 18

REASON_STATIC_CALL = 19

REASON_STATE_COLD_ACCESS = 20

Added in Berlin fork (Geth 1.10+)

Typeenum

sf.ethereum.type.v2.TransactionTrace.Type

TRX_TYPE_LEGACY = 0

All transactions that ever existed prior Berlin fork before EIP-2718 was implemented.

TRX_TYPE_ACCESS_LIST = 1

Transaction that specicy an access list of contract/storage_keys that is going to be used in this transaction.

Added in Berlin fork (EIP-2930).

TRX_TYPE_DYNAMIC_FEE = 2

Transaction that specifis an access list just like TRX_TYPE_ACCESS_LIST but in addition defines the max base gas gee and max priority gas fee to pay for this transaction. Transaction's of those type are executed against EIP-1559 rules which dictates a dynamic gas cost based on the congestion of the network.

TransactionTraceStatusenum

sf.ethereum.type.v2.TransactionTraceStatus

UNKNOWN = 0

SUCCEEDED = 1

FAILED = 2

REVERTED = 3