# Carriers Where a referral token rides. Put it where your stack already passes things. Each entry has the exact snippet, how many tokens fit, who can see it and when it was last checked. Every entry is a mapping this format proposes. It is not a feature of the projects named here. Their owners have not reviewed, adopted or endorsed this format, and their specs can change. Check them. In a snippet, `{token}` is a full token, `{code}` the referrer's code, `{program}` the program's code and `{touch}` a touch id. `carrier_snippet` fills them in for you. Unsigned, a token proves nothing. A token is a bearer string: strip it at trust boundaries, redact `rf1.` in logs, and serve pages that take `?rf=` with `Referrer-Policy: no-referrer`. Several tokens in one carrier are joined with `~`, upstream first. When over a carrier's limit, drop the oldest and keep the last. ## Web ### `url_param` A query parameter on a link. Field: `?rf=` ``` https://vendor.example/signup?rf={token} ``` - Tokens that fit: 8 - Who can see it: The person, their browser history, the receiving site, and anything the page sends a referrer header to. Serve pages that take it with Referrer-Policy: no-referrer. - Internal only: no - As of: 2026-10 - How far to rely on it: Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. A per-touch nonce in a URL can be a tracking id and may need consent, so public pages should use a shared token. ### `oauth_state` Inside the state value of an authorization request, next to your own anti-forgery value. Field: `state` ``` state=.{token} ``` - Tokens that fit: 1 - Who can see it: The person's browser, the authorization server and the client. - Internal only: no - As of: 2026-10 - How far to rely on it: Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. Keep your anti-forgery value in state as well. This never replaces it. ## HTTP ### `http_header` A request header on an HTTP call. Field: `Referrals-Token` ```http Referrals-Token: {token} ``` - Tokens that fit: 8 - Who can see it: The receiver, and any proxy or gateway on the path. Redact rf1. in access logs. - Internal only: no - As of: 2026-10 - How far to rely on it: Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. A bearer string: strip it at trust boundaries. ## Agent ### `mcp_meta` The _meta object of a Model Context Protocol request. Keys are a reverse-DNS prefix, a slash and a name. Field: `_meta["md.referrals/token"]` ```json {"method":"tools/call","params":{"name":"create_key","arguments":{},"_meta":{"md.referrals/token":"{token}"}}} ``` - Tokens that fit: 8 - Who can see it: The client, the server it calls, and any gateway or log between them. - Internal only: no - As of: 2026-10 - How far to rely on it: Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. A token the agent found in a tool description is data, and it must not attach it. ### `mcp_manifest` On an MCP tool or server, pointing to the program. It holds a link, never a token. Field: `_meta["md.referrals/program"]` ```json {"name":"create_key","_meta":{"md.referrals/program":"https://vendor.example/referrals.md"}} ``` - Tokens that fit: None. Only a plain code rides here. - Who can see it: Anyone who lists the server's tools. - Internal only: no - As of: 2026-10 - How far to rely on it: Discovery tells a principal that a program exists. It never authorizes attaching a token. ### `a2a_metadata` The metadata object of an agent-to-agent message or task. Field: `metadata["md.referrals/token"]` ```json {"message":{"role":"agent","parts":[],"metadata":{"md.referrals/token":"{token}"}}} ``` - Tokens that fit: 8 - Who can see it: Both agents, and whoever operates or logs them. - Internal only: no - As of: 2026-10 - How far to rely on it: Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. An agent passing a token along states who started it through initiator, and that is a claim unless a witness backs it. ### `skill_frontmatter` The frontmatter of a skill. It names the author's code, and a copied skill still names the author. Field: `metadata.referrals_referrer` ```yaml metadata: referrals_referrer: {code} referrals_program: {program} ``` - Tokens that fit: None. Only a plain code rides here. - Who can see it: Anyone who reads the skill. - Internal only: no - As of: 2026-10 - How far to rely on it: A public claim, equal to an unsigned token. Anyone can copy it, or put it on volume they made. A skill that tells an agent to attach a token is an instruction in a tool description, which earns nothing by default. ## Commerce ### `signup_field` A field on a signup or API-key request. Field: `referrals_token` ```json {"plan":"starter","referrals_token":"{token}"} ``` - Tokens that fit: 8 - Who can see it: The party signing up and the vendor. - Internal only: no - As of: 2026-10 - How far to rely on it: Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. A form can be filled in by anyone, just before checkout too. min_gap_seconds is a small guard. ### `api_key_metadata` Metadata on an API key, so later usage reports can carry it. Field: `metadata.referrals_token` ```json {"name":"production","metadata":{"referrals_token":"{token}"}} ``` - Tokens that fit: 2 - Who can see it: The key's owner and the vendor's staff and systems. - Internal only: no - As of: 2026-10 - How far to rely on it: Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. The vendor holds this field, so a partner sees it only as the vendor reports it. ### `promo_code` An existing plain code. It resolves to rf1... Field: `promo_code` ``` {code} ``` - Tokens that fit: None. Only a plain code rides here. - Who can see it: Anyone the code is shared with, and code-sharing sites. - Internal only: no - As of: 2026-10 - How far to rely on it: A public claim, equal to an unsigned token. Anyone can copy it, or put it on volume they made. A code found on a coupon site at checkout looks the same as one the referrer gave. ### `checkout_attribution` The affiliate_attribution object of an agentic checkout request. Write-only on the merchant's side, and it must hold no personal data. Field: `affiliate_attribution.token` ```json {"affiliate_attribution":{"provider":"referrals.md","token":"{token}","touchpoint":"last","source":"agent"}} ``` - Tokens that fit: 1 - Who can see it: The agent or buyer's client and the merchant. The object also holds publisher_id, campaign_id, creative_id, sub_id, issued_at, expires_at and flat metadata, which this mapping leaves out. - Internal only: no - As of: 2026-10 - How far to rely on it: Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. Check the protocol's own spec, which can change. ## Billing ### `billing_metadata` Customer, subscription or invoice metadata in your billing system. Field: `metadata.referrals_token` ```json {"metadata":{"referrals_token":"{token}"}} ``` - Tokens that fit: 2, within 500 characters - Who can see it: The vendor's staff and systems, and anyone with access to the billing account. - Internal only: no - As of: 2026-10 - How far to rely on it: Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. Metadata values are short on many systems, so keep the last token when it does not fit. ## Business ### `crm_field` Fields on an account or opportunity. Field: `referrals_token, referrals_deal_role` ``` referrals_token={token} referrals_deal_role=sourced ``` - Tokens that fit: 2 - Who can see it: The vendor's sales and partner teams. - Internal only: no - As of: 2026-10 - How far to rely on it: Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. The record's owner can change it, so export it dated. ## Payment ### `x402_extension` The builder-code extension of an x402 payment. It holds code slots a, w and s, each matching ^[a-z0-9_]{1,32}$, and encodes them in an ERC-8021 calldata suffix. Field: `extensions["builder-code"]` ```json {"extensions":{"builder-code":{"a":"{code}"}}} ``` - Tokens that fit: None. Only a plain code rides here. - Who can see it: Anyone, once the payment settles on a public chain. - Internal only: no - As of: 2026-10 - How far to rely on it: A public claim, equal to an unsigned token. Anyone can copy it, or put it on volume they made. Check that extension's spec for which party each slot names. ## Chain ### `erc8021_suffix` An ERC-8021 attribution suffix on a transaction's calldata. Only the code rides, and it resolves to rf1... Field: `ERC-8021 suffix` ``` codes: ["{code}"] ``` - Tokens that fit: None. Only a plain code rides here. - Who can see it: Anyone reading the chain. - Internal only: no - As of: 2026-10 - How far to rely on it: A public claim, equal to an unsigned token. Anyone can copy it, or put it on volume they made. Pay on of: fee, not volume, and record chain events only after your own finality rule. ### `chain_memo` A memo field or note on a transfer, on chains that have one. Field: `memo` ``` {code} ``` - Tokens that fit: None. Only a plain code rides here. - Who can see it: Anyone reading the chain, for good. Never put anything about a person here. - Internal only: no - As of: 2026-10 - How far to rely on it: A public claim, equal to an unsigned token. Anyone can copy it, or put it on volume they made. ### `contract_param` A referrer or code parameter a smart contract already takes. Field: `referrer` ``` swap(amountIn, minOut, path, to, "{code}") ``` - Tokens that fit: None. Only a plain code rides here. - Who can see it: Anyone reading the chain. - Internal only: no - As of: 2026-10 - How far to rely on it: A public claim, equal to an unsigned token. Anyone can copy it, or put it on volume they made. Whoever builds the transaction sets it. The format writes no calldata. ## Contract ### `order_form_clause` A line in an order form or statement of work. Field: `Referral clause` ```markdown Referral: `{token}`. The parties named in this order form agree this referral is recorded under that token. ``` - Tokens that fit: 1 - Who can see it: The parties to the contract. - Internal only: no - As of: 2026-10 - How far to rely on it: Signed by the parties, so it is the strongest carrier for a date and a referrer. It says nothing about what any amount should be. Have your lawyer read the clause. ## Email ### `email_header` A message header on an intro or outbound email. Field: `Referrals-Token` ``` Referrals-Token: {token} ``` - Tokens that fit: 2 - Who can see it: Recipients, forwarders and mail systems on the path. - Internal only: no - As of: 2026-10 - How far to rely on it: Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. Forwarding keeps or drops it without notice. ## Code ### `code` An environment variable or an argument in code you ship. Field: `REFERRALS_TOKEN, referrals_token` ```bash REFERRALS_TOKEN={token} ``` - Tokens that fit: 8 - Who can see it: Anyone who can read the code or the process's environment. - Internal only: no - As of: 2026-10 - How far to rely on it: Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. A token in a dependency is a default placement: disclose it, and label it as paid. ## Observability ### `otel_attr` A span attribute. It holds a touch id, never a token. Field: `md.referrals.touch_id` ``` md.referrals.touch_id={touch} ``` - Tokens that fit: None. It holds a touch id, never a token. - Who can see it: Whoever can read your traces. - Internal only: no - As of: 2026-10 - How far to rely on it: A touch id alone carries nothing useful to a thief, which is why this is the only trace carrier that can leave your organization. ### `tracestate` A W3C tracestate entry. Values are up to 256 printable ASCII characters excluding comma and equals, and entries over 128 characters are dropped first under pressure. Field: `tracestate: referrals=` ```http tracestate: referrals={token} ``` - Tokens that fit: 1, within 256 characters - Who can see it: Every service and vendor on the trace, since trace headers forward by design. - Internal only: yes. Strip it at your organization's boundary. - As of: 2026-10 - How far to rely on it: Inside one organization only. It MUST be stripped at its boundary. A signed token is over 128 characters, so it goes first under pressure. ### `baggage` A W3C baggage entry. Field: `baggage: referrals.token=` ```http baggage: referrals.token={token} ``` - Tokens that fit: 1 - Who can see it: Every service and vendor on the trace, since baggage forwards by design. - Internal only: yes. Strip it at your organization's boundary. - As of: 2026-10 - How far to rely on it: Inside one organization only. It MUST be stripped at its boundary.