Skip to main content
Attribution tags let you mark transactions as coming from your app — so on-chain activity can be credited back to you for programs like MiniPay leaderboards and hackathon tracking. Celo’s implementation follows ERC-8021.

How It Works

ERC-8021 appends a small suffix to a transaction’s calldata. The suffix is invisible to the contract being called — the EVM discards trailing bytes — so adding it never changes execution semantics. It just makes the transaction identifiable as having come through your app to anyone reading calldata off-chain.
Tagging a transaction is open to everyone. Whether a code gets credited on a leaderboard or rewards program is resolved at the registry/indexer layer, not at the tagging step.

Install

viem is an optional peer dependency — only required if you call verifyTx to decode a tag from a transaction hash. The SDK exports four functions:

Quickstart

If you’ve been issued a code (celo_xxxxxxxx) — for example through a hackathon registration — pass it directly:
Any string matching [a-z0-9_] (1–32 characters) is a valid code. If a program assigned you a code, it must be present in the suffix — leaderboards and reward programs only credit the assigned code, not one you derive yourself with codeFromHostname. You can include both:

Tagging a Contract Call

Concatenate your encoded calldata with the suffix:
With wagmi, pass dataSuffix directly and wagmi handles the concatenation:

The Layering Rule

ERC-8021 suffixes can carry multiple codes, but each code should only be added by the entity it represents:
  • Your app code — added by your app, as shown above.
  • A platform code like minipay — added by the platform itself (the wallet or cohort layer), never by your app.
Adding a platform code from your own app would falsely claim every transaction ran inside that platform, polluting attribution data.

x402 Settlements

When a payment is settled through an x402 facilitator, the facilitator submits the transaction, not your wallet, so you cannot append the suffix yourself. ERC-8021 covers this with a role-based tag (Schema 2) that the facilitator writes: your app is credited in the a (app) field, the facilitator identifies itself in w, and the paying client can add s.
Not live yet. The Celo facilitator at api.x402.celo.org does not write Schema 2 tags today, so x402 settlements on Celo currently carry no attribution tag. The facilitator-side implementation is under review upstream in x402-rs/x402-rs#99 and ships as soon as it merges. This page is updated when it goes live.
Once live, your app code travels through the standard x402 builder-code extension and needs no registration with the facilitator:
  • Your resource server declares the code in its 402 response under extensions["builder-code"].info.a (the reference middleware does this with declareBuilderCodeExtension from @x402/extensions).
  • The client echoes it in the payment payload; a client paying on its own behalf adds its code under extensions["builder-code"].info.s.
  • The facilitator reads both, adds its own w, and appends the suffix to the settlement calldata.
You can declare the code now: it is ignored until the facilitator update ships, then applied automatically. It applies to x402 v2 payments only (v1 has no extensions field) and, at first, to settlements in USDC, USDâ‚® and USAâ‚®.

Verifying It Worked

verifyTx returns null (never throws) if no tag is found. For offline decoding without an RPC call, use fromDataSuffix(rawCalldata) instead.
Some smart-account / bundler flows (ERC-4337 bundlers, meta-tx relayers) rewrite calldata and can strip trailing bytes. Verify on-chain with verifyTx before relying on tags in production.

Resources