Skip to main content

Onchain Attribution

JTBD 8 — precondition
Live on day one, or every other job flies blind
Onchain attribution is not a measurement job. It is the instrument under every other marketing job. Without it, no loop closes. Content, loyalty, and ecosystem channels all produce unverifiable claims.
What it links
Offchain events (ad click, AI citation, protocol discovery, MCP tool call) to verified onchain transactions. The chain is the source of truth; everything before it is a claim.
Why it cannot wait
Retroactive attribution is unreliable. Wallet addresses seen before the attribution instrument is live cannot be matched to acquisition events that were never recorded.
Privacy boundary
Linking a wallet address to offchain identity is a privacy decision, not a measurement decision. That call is human, not AI. Define the boundary before implementation begins.

Purpose​

Every other marketing job in this work chart produces a claim. Onchain attribution is the instrument that converts claims into verified measurements:

  • The AEO cycle claims it earned a citation that drove a transaction — attribution verifies it
  • The content calendar claims a depth page drove developer adoption — attribution verifies it
  • The loyalty programme claims it increased holder retention — attribution verifies it
  • The ecosystem integration claims it drove transactions from a new channel — attribution verifies it

Without attribution live on day one, the first six months of marketing activity produces data you cannot trust. Wallet addresses seen later cannot be matched to acquisition events that were not recorded.

The instrument has a non-negotiable sequencing requirement: it must be live before the content calendar launches, before the loyalty programme designs, and before ecosystem integrations go live. This is not a job to complete after other jobs are running. It is the floor all other jobs stand on.

Process​

1. Define the attribution model​

Before implementation, decide what the model must link and what it explicitly will not link. Attribution model decisions are irreversible once the data starts accumulating. Changing the model retroactively produces inconsistent historical data.

What to link (the chain):

  • Offchain event → session identifier → wallet address → onchain transaction

Offchain event types to capture:

  • Ad click or organic search arrival — standard UTM attribution
  • AI-citation referral — traffic arriving from an AI answer surface (Perplexity, ChatGPT, Gemini, Claude); identify by referrer or session pattern
  • Protocol discovery — arrival via a protocol registry, ecosystem listing, or developer documentation link
  • MCP tool call — an agent invoking your MCP endpoint; the call itself is an attribution event
  • Manifest fetch — an agent reading your /.well-known/agent.json; a leading indicator of transaction intent

What the model will not link (privacy boundary):

  • Wallet address to real-world identity — unless the user has explicitly consented as part of a KYC-required flow
  • Cross-session tracking without explicit consent
  • Transaction amounts to user profiles — the attribution model needs to know a transaction happened and which channel it came from; it does not need the amount unless computing CLTV

This boundary is set by humans before implementation. It shapes every downstream data structure. Do not defer it to a later compliance review.

2. Wallet attribution architecture​

The attribution chain has three segments:

Segment A — offchain event capture

Standard web analytics (session ID, referrer, UTM parameters) extended with:

  • AI-referral detection: pattern-match referrers from known AI answer surfaces, or use a dedicated utm_source=ai-citation parameter on links submitted to AI platforms
  • Agent-event capture: log MCP tool calls and manifest fetches with a request ID that persists through the session

Segment B — wallet connect event

When a user connects a wallet (to initiate checkout, claim a loyalty token, or authenticate), log:

  • Session ID from Segment A
  • Wallet address (pseudonymised where privacy model requires)
  • Connection timestamp
  • Connection context (checkout flow, loyalty claim, authentication)

This is the join event. It links an offchain session to an onchain identity.

Segment C — onchain transaction verification

For each wallet address logged in Segment B, monitor the relevant chain(s) for transactions to your contract addresses. Record:

  • Transaction hash — the chain's verifiable proof
  • Block timestamp — authoritative confirmation time
  • Transaction value and token type
  • Contract called (checkout contract, loyalty token claim, governance vote)

Join Segment C to Segment B via wallet address. Join Segment B to Segment A via session ID. The result: offchain acquisition event → verified onchain transaction.

3. Instrument-gap log​

As the attribution chain is built, maintain an explicit log of what is currently measured and what is not. The instrument-gap log is the honest record of where attribution is live and where it is still a claim.

The log has three columns:

  • Event type — which acquisition event (AI citation, ad click, MCP tool call, etc.)
  • Attribution status — live | partial | not yet instrumented
  • Gap note — what is missing and when it is targeted to be live heuristic

Publish the instrument-gap log internally. Every other marketing job that relies on attribution data must know which of its measurements are verified and which are estimates. An unannounced gap is a silent lie.

4. Privacy-guardrail documentation​

Document the privacy boundary decisions made in Step 1. The documentation serves three purposes:

  • Internal alignment — every team member who touches user data knows what is permitted
  • User disclosure — the basis for clear, accurate privacy notices
  • Compliance record — evidence of deliberate privacy design, not retroactive justification

The documentation names:

  • Which data is collected and retained
  • Which data is pseudonymised vs identified
  • Retention period per data type heuristic
  • Who has access
  • The wallet-to-identity linkage policy

5. Channel metrics baseline​

Once attribution is live, establish a baseline within the first 30 days heuristic. The baseline is the starting point for every channel comparison:

  • Onchain CAC per channel (cost of acquiring one verified transaction holder, by channel)
  • Conversion rate from each offchain event type to verified onchain transaction heuristic
  • Time from first session to first transaction, by segment heuristic
  • Attribution completeness — percentage of all transactions that have a traceable acquisition event

The baseline makes every subsequent measurement meaningful. Without it, "improvement" is relative to nothing.

Inputs / Outputs​

Inputs

  • Privacy model decision — what the attribution chain will and will not link (human decision, made before implementation)
  • Chain selection — which blockchain(s) your service transacts on (determines which indexer to monitor)
  • Contract address list — the onchain addresses that represent purchases, loyalty claims, and governance events
  • Offchain analytics infrastructure — web analytics, server logs, MCP endpoint logs

Outputs

  • Wallet attribution model — live, with documented privacy guardrails
  • Instrument-gap log — which event types are currently measured and which are not
  • Channel metrics baseline — onchain CAC, conversion rates, time-to-transaction by segment
  • Privacy-guardrail documentation — the boundary decisions and their rationale
  • Attribution data feed — consumed by all other marketing jobs for measurement

Quality Standards​

The attribution instrument is live when:

  • At least one full offchain → wallet → onchain chain is verified end-to-end with a real transaction
  • The instrument-gap log is published internally with an honest status per event type
  • Privacy guardrails are documented and reviewed before any user-facing data collection begins
  • The baseline metrics have been calculated over a minimum 30-day heuristic live period

The instrument is not live when:

  • Attribution is running only in analytics (offchain only) with no wallet join
  • The instrument-gap log does not exist or is not shared with the teams relying on the data
  • Privacy decisions are deferred pending "the compliance review" — that review must happen before the instrument goes live

Metrics​

The attribution instrument produces the measurement data for every other job. Its own health metrics are:

  • Attribution completeness rate — percentage of verified onchain transactions with a traceable offchain acquisition event; target ≥ 80% heuristic after 90 days live
  • Instrument-gap closure rate — how many event types moved from "not yet instrumented" to "live" per quarter
  • Data latency — time from onchain transaction to attribution record available for reporting heuristic
  • Privacy-incident count — the only acceptable number is zero; any linkage outside the documented guardrails is an incident

Failure Modes​

Starting after launch. Every day the attribution instrument is not live is a day of acquisition events that cannot be attributed. Retroactive matching from wallet addresses to unknown prior sessions is unreliable at best and impossible for agent transactions with no session context.

Measuring offchain only. Web analytics that stop at wallet connect without verifying the onchain transaction measure intent, not outcome. An agent that fetches your manifest and does not transact looks identical to one that does, until the chain confirms. The chain is the truth.

Deferring the privacy-boundary decision. The data structure that determines what is retained and what is discarded must be designed before data starts accumulating. A privacy decision made after six months of data collection either requires retroactive deletion (expensive, often incomplete) or forces retention of data that should never have been kept.

Treating attribution as a marketing tool, not an instrument. Attribution data answers whether marketing activities produced verified transactions. It is not a tool for maximising clicks or sessions. An attribution model optimised to inflate reported numbers (last-click attribution applied to a multi-touch journey) produces comfortable lies, not useful measurements.

Not publishing the instrument-gap log. Every job that relies on attribution data and does not know the gaps will produce measurements it believes are complete. The gap log is the difference between "we measured this" and "we think we measured this". Publish it.

Human / AI Split​

Human judgment required

  • Privacy-boundary decisions — what the attribution chain is permitted to link; this is an ethical and legal judgment, not a measurement problem
  • Retention policy design — how long data is kept per type; requires legal review in most jurisdictions
  • Instrument-gap prioritisation — which unattributed event types to instrument next, given engineering capacity
  • Privacy-incident response — if a linkage outside the documented guardrails occurs, human judgment determines the response

AI-executable

  • Monitoring chain addresses for transactions matching the attribution model
  • Joining session IDs to wallet connect events in real time
  • Calculating attribution completeness rate and flagging when it falls below threshold
  • Generating the instrument-gap log status from data pipeline health checks
  • Producing channel metrics baselines from the attributed transaction dataset

Context​

Questions​

  • Is your attribution instrument live before your content calendar, loyalty programme, and ecosystem integrations — or are those jobs already running blind?
  • Where is the seam between "this channel drove a session" and "this session became a verified transaction" — and is that seam instrumented?
  • Who in your organisation made the privacy-boundary decision, and is it documented — or is it implicit in whatever the analytics tool captured by default?