{ "referrals": 3, "status": "draft", "note": "A proposal. New names are added when there is one public use, through https://referrals.md/feedback. Token codes are never reassigned.", "record_types": { "party": { "prefix": "pt_", "derived": false }, "program": { "prefix": "rp_", "derived": false }, "agreement": { "prefix": "ag_", "derived": false }, "touch": { "prefix": "tc_", "derived": false }, "event": { "prefix": "ev_", "derived": false }, "void": { "prefix": "vd_", "derived": false }, "adjustment": { "prefix": "aj_", "derived": false }, "attribution": { "prefix": "ab_", "derived": true }, "accrual": { "prefix": "ac_", "derived": true }, "statement": { "prefix": "st_", "derived": false }, "signoff": { "prefix": "sg_", "derived": false }, "payout": { "prefix": "po_", "derived": false }, "dispute": { "prefix": "dp_", "derived": false }, "period_close": { "prefix": "pc_", "derived": false }, "tax_document": { "prefix": "td_", "derived": false }, "ledger": { "prefix": "lg_", "derived": false }, "index": { "prefix": "ix_", "derived": false } }, "extension_prefix": "xr_", "customer_prefix": "cu_", "party_kinds": [ "person", "company", "agent", "harness", "model_provider", "gateway", "skill", "mcp_server", "marketplace", "reseller", "consultancy", "creator", "wallet", "protocol", "other" ], "handle_schemes": [ "domain", "did", "wallet", "agent", "local" ], "categories": [ "saas", "api_usage", "ai_native", "enterprise", "bizdev", "onchain", "stablecoin", "marketplace", "creator", "mixed" ], "program_statuses": [ "draft", "open", "invite_only", "closed" ], "net_of": [ "tax", "discount", "processor_fee", "marketplace_fee", "credits_applied" ], "touch_kinds": { "recommendation": "r", "citation": "c", "tool_call": "t", "tool_install": "i", "skill_install": "s", "mcp_connect": "m", "model_route": "g", "handoff": "h", "default_placement": "p", "marketplace_listing": "l", "link": "w", "code": "k", "content": "n", "deal_registration": "d", "intro": "b", "co_sell": "o", "reseller_order": "e", "marketplace_offer": "f", "contract_clause": "u", "builder_code": "a", "memo": "y", "contract_param": "q", "other": "x" }, "touch_kind_groups": { "Agent": [ "recommendation", "citation", "tool_call", "tool_install", "skill_install", "mcp_connect", "model_route", "handoff", "default_placement", "marketplace_listing" ], "Web": [ "link", "code", "content" ], "Business": [ "deal_registration", "intro", "co_sell", "reseller_order", "marketplace_offer", "contract_clause" ], "On-chain": [ "builder_code", "memo", "contract_param" ], "Other": [ "other" ] }, "disclosure_strict_kinds": [ "recommendation", "citation", "default_placement", "model_route", "tool_call", "handoff" ], "disclosure_exempt_kinds": [ "builder_code", "memo", "contract_param" ], "initiators": { "user_asked": "a", "agent_suggested": "s", "operator_prompt": "o", "tool_result": "r", "retrieved_content": "c", "tool_description": "t", "human": "h", "unknown": "x" }, "injected_initiators": [ "retrieved_content", "tool_description" ], "disclosure_flags": { "d": "paid and shown to a person", "a": "paid and shown to an agent", "u": "unpaid", "n": "not stated" }, "shown_to": [ "person", "agent", "none" ], "event_kinds": { "Acquisition": [ "signup", "trial_start", "install", "connect", "activation" ], "Commerce": [ "purchase", "subscription_start", "subscription_renew", "subscription_upgrade", "subscription_downgrade", "subscription_cancel", "seat_change", "payment" ], "Usage": [ "usage" ], "Business": [ "deal_registered", "deal_accepted", "deal_rejected", "deal_opened", "deal_stage", "deal_won", "deal_lost", "deal_renewal", "deal_merged", "contract_signed", "intro_made", "meeting_held", "milestone_met" ], "On-chain": [ "chain_transfer", "chain_swap", "chain_deposit", "chain_fee", "wallet_created", "onramp", "offramp", "stablecoin_settlement" ], "Reversal": [ "refund", "chargeback", "write_off", "reorg", "fraud_reversal" ], "Service": [ "sla_met", "sla_breach" ] }, "source_systems": [ "billing", "crm", "meter", "ledger", "chain", "marketplace", "partner_portal", "contract", "support", "warehouse", "manual", "other" ], "evidence_grades": [ "self_reported", "source_ref", "source_hash", "chain_ref", "two_signed" ], "bases": [ "flat", "percent", "per_unit", "tiered", "track" ], "of_fields": [ "amount", "net", "fee", "margin", "tcv", "acv", "first_year" ], "models": [ "last_touch", "first_touch", "linear", "weighted", "role_split", "fixed", "each" ], "match_keys": [ "token", "code", "deal", "customer", "account", "wallet" ], "rounding": [ "half_even", "half_up", "down" ], "cycles": [ "weekly", "monthly", "quarterly", "on_demand" ], "periods": [ "month", "quarter", "year", "lifetime" ], "cap_per": [ "event", "customer", "deal", "referrer_period", "program_period" ], "accrual_kinds": [ "earn", "true_up", "reverse", "adjust", "restate", "floor" ], "accrual_states": [ "voided", "contested", "below_evidence_min", "no_payee", "paid", "part_paid", "held", "payable" ], "rails": [ "ach", "wire", "sepa", "card", "check", "stablecoin", "crypto", "credits", "invoice_offset", "marketplace", "other" ], "void_reasons": [ "fraud", "error", "duplicate", "bad_hmac", "other" ], "adjustment_reasons": [ "goodwill", "retainer", "forfeit", "write_off_receivable", "correction", "other" ], "dispute_statuses": [ "open", "answered", "resolved", "withdrawn" ], "dispute_reasons": [ "missing_credit", "wrong_share", "wrong_rate", "wrong_amount", "late_payment", "reversal_disputed", "terms_mismatch", "fraud_claim", "other" ], "sla_metrics": [ "statement_days", "payout_days", "deal_response_days", "dispute_response_days", "uptime_pct", "response_minutes", "custom" ], "regulated_fields": [ "securities", "insurance", "credit", "real_estate_settlement", "healthcare", "legal_services", "government_buyer", "money_transmission", "gambling", "other" ], "crit_features": [ "tiered", "track", "high_water", "step", "cap", "sla", "sla_multiplier", "floors", "split", "weighted", "role_split", "fixed", "each", "accrual_scale", "witness" ], "policy_fields": { "paid_recommendations": [ "never", "ask", "disclosed" ], "agents_may_join_programs": [ "never", "ask" ], "agents_may_mint_tokens": [ "never", "ask", "yes" ], "share_customer_ref": [ "never", "salted_only" ] }, "policy_defaults": { "paid_recommendations": "disclosed", "agents_may_join_programs": "ask", "agents_may_mint_tokens": "ask", "share_customer_ref": "never" }, "limits": { "depth": 16, "string": 4096, "freeText": 280, "decimalDigits": 78, "rules": 64, "tiers": 64, "tokensPerEvent": 8, "candidatesPerEvent": 1024, "days": 3650, "actsForHops": 8 }, "api_limits": { "bodyBytes": 1048576, "records": 10000 }, "iso_scales": { "BIF": 0, "CLP": 0, "DJF": 0, "GNF": 0, "ISK": 0, "JPY": 0, "KMF": 0, "KRW": 0, "PYG": 0, "RWF": 0, "UGX": 0, "UYI": 0, "VND": 0, "VUV": 0, "XAF": 0, "XOF": 0, "XPF": 0, "BHD": 3, "IQD": 3, "JOD": 3, "KWD": 3, "LYD": 3, "OMR": 3, "TND": 3, "CLF": 4, "UYW": 4 }, "wire_names": { "httpHeader": "Referrals-Token", "urlParam": "rf", "mcpToken": "md.referrals/token", "mcpProgram": "md.referrals/program", "field": "referrals_token", "otelTouch": "md.referrals.touch_id", "linkRel": "https://referrals.md/rel/program", "tracestateKey": "referrals", "baggageKey": "referrals.token", "cloudEventType": "md.referrals.event." }, "codes": { "errors": { "E01": { "code": "E01", "name": "bad_json", "message": "Not valid JSON under the format's rules: fractional or exponent numbers, -0, a lone surrogate, a byte order mark or a duplicate key." }, "E02": { "code": "E02", "name": "missing_field", "message": "A required field is missing." }, "E03": { "code": "E03", "name": "bad_value", "message": "A field has a value outside its grammar or list." }, "E04": { "code": "E04", "name": "bad_id", "message": "The id does not match its derivation." }, "E05": { "code": "E05", "name": "null_field", "message": "A record holds null. Absent means null; never write it." }, "E06": { "code": "E06", "name": "bad_time", "message": "A timestamp is not UTC with seconds and a Z, or is not a real time." }, "E07": { "code": "E07", "name": "bad_amount", "message": "An amount is not a decimal string with exactly the asset's scale digits." }, "E08": { "code": "E08", "name": "bad_rate", "message": "A rate does not match the percent grammar: 11% or 0.125%, with no trailing zeros." }, "E09": { "code": "E09", "name": "undeclared_asset", "message": "This asset needs its scale in the assets table." }, "E10": { "code": "E10", "name": "bad_handle", "message": "A party handle is not in normal form." }, "E11": { "code": "E11", "name": "bad_token", "message": "A token does not match the grammar." }, "E12": { "code": "E12", "name": "conflict", "message": "Two records have the same id and different content." }, "E13": { "code": "E13", "name": "banned_key", "message": "A key named __proto__, constructor or prototype, or a key that is not ASCII." }, "E14": { "code": "E14", "name": "over_limit", "message": "A value is over one of the format's limits." }, "E15": { "code": "E15", "name": "unknown_crit", "message": "The program requires a feature this engine does not know, so it refuses to compute." }, "E16": { "code": "E16", "name": "crit_missing", "message": "The program uses a feature and does not list it in crit." }, "E20": { "code": "E20", "name": "bad_rule", "message": "A rule is missing what its basis needs, or has an unknown basis." }, "E21": { "code": "E21", "name": "duplicate_rule", "message": "Two rules have the same id." }, "E22": { "code": "E22", "name": "bad_tiers", "message": "Tiers must ascend from 0 with rates in the percent grammar." }, "E23": { "code": "E23", "name": "shares_over_100", "message": "Shares in one table add to more than 100%." }, "E24": { "code": "E24", "name": "bad_override", "message": "An override names an unknown rule, deletes a field or changes attribution." }, "E25": { "code": "E25", "name": "cap_asset", "message": "A cap's asset is not the accrual's asset." }, "E26": { "code": "E26", "name": "model_config", "message": "The attribution model is missing what it needs: weights, role_shares or shares." }, "E27": { "code": "E27", "name": "duplicate_code", "message": "Two active agreements use one referrer code in a program." }, "E28": { "code": "E28", "name": "duplicate_program_code", "message": "Two programs with one code in one file." }, "E30": { "code": "E30", "name": "wrong_author", "message": "Only the program's payer can write this record type. The math skips it." }, "E31": { "code": "E31", "name": "customer_and_wallet", "message": "An event sets both customer and wallet." }, "E32": { "code": "E32", "name": "bad_reversal", "message": "A reversal is missing reverses, names an unknown event, or has a different asset." }, "E33": { "code": "E33", "name": "net_mismatch", "message": "net is not amount minus the sum of deductions." }, "E34": { "code": "E34", "name": "bad_restate", "message": "A restating event has the same source id as the one it restates, or names an unknown event." }, "E35": { "code": "E35", "name": "token_touch_mismatch", "message": "A touch's fixed fields disagree with its token, so the record is invalid." }, "E36": { "code": "E36", "name": "bad_chain_event", "message": "A chain event has an owner, or lacks program or a full chain object." }, "E37": { "code": "E37", "name": "acts_for_cycle", "message": "An acts_for chain has a cycle or is over 8 hops." }, "E38": { "code": "E38", "name": "bad_key", "message": "A party key is malformed or of small order." }, "E39": { "code": "E39", "name": "bad_source", "message": "An event's source is missing, or a source id or url breaks the identifier grammar." }, "E40": { "code": "E40", "name": "chain_break", "message": "A chained ledger has a broken prev or a reordered line." }, "E41": { "code": "E41", "name": "not_canonical", "message": "A chained ledger line is not canonical JSON." }, "E42": { "code": "E42", "name": "root_mismatch", "message": "A statement's root does not match its accruals." }, "E43": { "code": "E43", "name": "opening_mismatch", "message": "A statement's opening is not its prior statement's closing." }, "E44": { "code": "E44", "name": "totals_mismatch", "message": "A statement's totals do not recompute from its accruals and payouts." }, "E45": { "code": "E45", "name": "bad_signature", "message": "A signature does not check out against the signer's key in force." }, "E46": { "code": "E46", "name": "late_revision", "message": "A statement revision after a signoff or payout on that period." } }, "warnings": { "W01": { "code": "W01", "name": "unsigned_agent_kinds", "message": "This paying program accepts unsigned tokens on agent kinds. Anyone can copy or invent one for a known code, as with a plain affiliate link. Set attribution.token.signed." }, "W02": { "code": "W02", "name": "net_undefined", "message": "A rule uses of: net and net_of does not say what net means. This is the most common commission dispute." }, "W03": { "code": "W03", "name": "lock_short", "message": "customer_lock_days is shorter than the longest recurring term, so later payments can earn nothing." }, "W04": { "code": "W04", "name": "first_claim_burn", "message": "single_customer tokens: whoever presents a token first claims it, so a stolen token can burn a real customer's credit." }, "W05": { "code": "W05", "name": "volume_on_chain", "message": "A percent of amount on a chain transfer, swap or deposit rewards wash volume. Use of: fee." }, "W06": { "code": "W06", "name": "token_trade_pay", "message": "Pay tied to a sale or trade of tokens or securities may require a license. Ask a lawyer first." }, "W07": { "code": "W07", "name": "pay_on_others_sales", "message": "A split pays someone on another party's sales. Keep it to one level." }, "W08": { "code": "W08", "name": "long_lock", "message": "A customer lock over 365 days gives one touch a long claim on a customer. State it in the program's plain text." }, "W09": { "code": "W09", "name": "internal_carrier", "message": "tracestate and baggage forward across services. Use them inside one organization only and strip them at its boundary." }, "W10": { "code": "W10", "name": "ledger_in_program", "message": "A program file holds a ledger section. Never publish your ledger." }, "W11": { "code": "W11", "name": "terms_differ", "message": "The JSON and Markdown forms of this program have different terms hashes. The JSON wins." }, "W12": { "code": "W12", "name": "no_holdback", "message": "holdback_days or clawback_days is 0 on a paying rule, so a refund can land after a payout." }, "W13": { "code": "W13", "name": "source_many_kinds", "message": "One source id appears under several event kinds, and a rule fires on more than one. That can pay twice." }, "W14": { "code": "W14", "name": "no_end_rule", "message": "settlement.on_end is not set, so nothing says what happens to a small balance when a partner leaves." }, "W15": { "code": "W15", "name": "wallet_only", "message": "wallet_only_payees pays a party known only by a wallet. Whoever pays handles identity, tax and sanctions checks." }, "W16": { "code": "W16", "name": "conduct_flag_only", "message": "conduct is set to flag, so injected or self-referred touches can still earn." }, "W17": { "code": "W17", "name": "regulated_other", "message": "Referral pay in this field is restricted in many places. Ask a lawyer first." }, "W18": { "code": "W18", "name": "unknown_fields", "message": "Fields the format does not define are kept and hashed but do nothing. Check for typos, or name them x-/." }, "W19": { "code": "W19", "name": "shared_agent_token", "message": "A shared token on an agent kind has no time of its own, so windows run from the first event, not the recommendation." }, "W20": { "code": "W20", "name": "disclosure_unstated", "message": "A touch with no disclosure state earned. A short link proves nothing about disclosure, and the referrer still carries the duty." }, "W21": { "code": "W21", "name": "payee_held", "message": "An accrual is held because its referrer has no agreement or no identified payee. Add one agreement line to release it." }, "W22": { "code": "W22", "name": "tracker_mixed_codes", "message": "A ledger holds tokens for a program code it does not know, so they compute nothing yet." }, "W23": { "code": "W23", "name": "terms_not_found", "message": "An agreement pins a terms hash that matches no version of the program supplied. Send that version, or fix the hash." } }, "refusals": { "R1": { "code": "R1", "name": "hidden_pay", "message": "Hidden pay: this removes or forbids disclosure of a paid recommendation." }, "R2": { "code": "R2", "name": "pay_for_recruiting", "message": "Pay for recruiting: pay for bringing in referrers rather than customers, or split depth above one." }, "R3": { "code": "R3", "name": "pay_to_buyer_staff", "message": "Pay to a buyer's employee, adviser or official can be bribery, and telling the employer may not cure it." }, "R4": { "code": "R4", "name": "promised_returns", "message": "Promised returns or income: yield, guaranteed profit, investment or earnings claims." }, "R5": { "code": "R5", "name": "identifiers_or_secrets", "message": "Direct identifiers or secrets in a record: email addresses, phone numbers, card numbers, private keys, seed phrases, API keys or tax ids. Use an opaque ref, and keep keys on your own machine." }, "R6": { "code": "R6", "name": "self_dealing", "message": "Self-dealing instructions: wash trades or refer-yourself loops." }, "R7": { "code": "R7", "name": "regulated_pay", "message": "Transaction-based referral pay is restricted or banned in this field. See a lawyer first. This tool will not build it." } }, "exclusions": { "X01": { "code": "X01", "name": "after_event", "message": "The touch is later than the event." }, "X02": { "code": "X02", "name": "outside_window", "message": "The touch is older than the program's window." }, "X03": { "code": "X03", "name": "voided", "message": "A void names this touch." }, "X04": { "code": "X04", "name": "kind_not_allowed", "message": "The program does not pay for this kind of touch." }, "X05": { "code": "X05", "name": "initiator_not_allowed", "message": "This touch came from retrieved content or a tool description, so it earns nothing." }, "X06": { "code": "X06", "name": "not_disclosed", "message": "This touch is not marked as disclosed, or claims to be unpaid, so it earns nothing." }, "X07": { "code": "X07", "name": "self_referral", "message": "The referrer and the customer look like the same party." }, "X08": { "code": "X08", "name": "not_enrolled", "message": "The referrer had no active agreement." }, "X09": { "code": "X09", "name": "token_invalid", "message": "The token does not meet the program's signing rule, or its signature does not check out." }, "X10": { "code": "X10", "name": "token_replayed", "message": "Another customer claimed this single-customer token first." }, "X11": { "code": "X11", "name": "not_accepted", "message": "This kind of touch counts only after the payer accepts it." }, "X12": { "code": "X12", "name": "protected_by_other", "message": "An earlier accepted touch of an exclusive kind holds this." }, "X13": { "code": "X13", "name": "lower_precedence", "message": "A touch of a higher-precedence kind qualified." }, "X14": { "code": "X14", "name": "no_share", "message": "The model gives this touch no share." }, "X15": { "code": "X15", "name": "locked_to_other", "message": "This customer is locked to other touches." }, "X16": { "code": "X16", "name": "unknown_referrer", "message": "The referrer code has no agreement." }, "X17": { "code": "X17", "name": "too_close", "message": "The touch is closer to the event than the program's minimum gap." }, "X18": { "code": "X18", "name": "unwitnessed", "message": "This program needs a witness, and the touch has none." } }, "flags": { "F01": { "code": "F01", "name": "self_referral_candidate", "message": "Same root, wallet or domain on the referrer and the customer." }, "F02": { "code": "F02", "name": "fast_conversion", "message": "A conversion within seconds of the touch." }, "F03": { "code": "F03", "name": "nonce_reuse", "message": "One nonce on many customers under a single-customer token." }, "F04": { "code": "F04", "name": "many_referrers", "message": "One customer touched by many referrers in a short time." }, "F05": { "code": "F05", "name": "injected_initiator", "message": "Touches that came from retrieved content or tool descriptions." }, "F06": { "code": "F06", "name": "loop", "message": "A via or acts_for cycle." }, "F07": { "code": "F07", "name": "wash_pattern", "message": "On-chain events with the same from and to, or round trips in a short window." }, "F08": { "code": "F08", "name": "touch_spike", "message": "A sudden rise in one referrer's touches with no rise in conversions." }, "F09": { "code": "F09", "name": "high_reversal_rate", "message": "A high share of this referrer's accruals were reversed." }, "F10": { "code": "F10", "name": "overlapping_usage", "message": "Usage reports with overlapping periods, not linked by restates." }, "F11": { "code": "F11", "name": "token_record_mismatch", "message": "A token's flags disagree with the touch record." }, "F12": { "code": "F12", "name": "backdated_token", "message": "A token's iat is far earlier than the payer's first sighting." }, "F13": { "code": "F13", "name": "one_source_many_kinds", "message": "One source id under several event kinds." }, "F14": { "code": "F14", "name": "shared_payout_ref", "message": "One payout reference across several parties." } } }, "carriers": [ { "id": "url_param", "layer": "web", "label": "Link", "field": "?rf=", "where": "A query parameter on a link", "snippet": "https://vendor.example/signup?rf={token}", "lang": "text", "max_tokens": 8, "carries": "token", "who_can_see": "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": false, "as_of": "2026-10", "trust": "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." }, { "id": "http_header", "layer": "http", "label": "HTTP API", "field": "Referrals-Token", "where": "A request header on an HTTP call", "snippet": "Referrals-Token: {token}", "lang": "http", "max_tokens": 8, "carries": "token", "who_can_see": "The receiver, and any proxy or gateway on the path. Redact rf1. in access logs.", "internal_only": false, "as_of": "2026-10", "trust": "Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. A bearer string: strip it at trust boundaries." }, { "id": "mcp_meta", "layer": "agent", "label": "MCP request", "field": "_meta[\"md.referrals/token\"]", "where": "The _meta object of a Model Context Protocol request. Keys are a reverse-DNS prefix, a slash and a name", "snippet": "{\"method\":\"tools/call\",\"params\":{\"name\":\"create_key\",\"arguments\":{},\"_meta\":{\"md.referrals/token\":\"{token}\"}}}", "lang": "json", "max_tokens": 8, "carries": "token", "who_can_see": "The client, the server it calls, and any gateway or log between them.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "mcp_manifest", "layer": "agent", "label": "MCP manifest", "field": "_meta[\"md.referrals/program\"]", "where": "On an MCP tool or server, pointing to the program. It holds a link, never a token", "snippet": "{\"name\":\"create_key\",\"_meta\":{\"md.referrals/program\":\"https://vendor.example/referrals.md\"}}", "lang": "json", "max_tokens": 0, "carries": "code", "who_can_see": "Anyone who lists the server's tools.", "internal_only": false, "as_of": "2026-10", "trust": "Discovery tells a principal that a program exists. It never authorizes attaching a token." }, { "id": "a2a_metadata", "layer": "agent", "label": "Agent to agent", "field": "metadata[\"md.referrals/token\"]", "where": "The metadata object of an agent-to-agent message or task", "snippet": "{\"message\":{\"role\":\"agent\",\"parts\":[],\"metadata\":{\"md.referrals/token\":\"{token}\"}}}", "lang": "json", "max_tokens": 8, "carries": "token", "who_can_see": "Both agents, and whoever operates or logs them.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "skill_frontmatter", "layer": "agent", "label": "Skill file", "field": "metadata.referrals_referrer", "where": "The frontmatter of a skill. It names the author's code, and a copied skill still names the author", "snippet": "metadata:\n referrals_referrer: {code}\n referrals_program: {program}", "lang": "yaml", "max_tokens": 0, "carries": "code", "who_can_see": "Anyone who reads the skill.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "signup_field", "layer": "commerce", "label": "Signup form", "field": "referrals_token", "where": "A field on a signup or API-key request", "snippet": "{\"plan\":\"starter\",\"referrals_token\":\"{token}\"}", "lang": "json", "max_tokens": 8, "carries": "token", "who_can_see": "The party signing up and the vendor.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "api_key_metadata", "layer": "commerce", "label": "API key", "field": "metadata.referrals_token", "where": "Metadata on an API key, so later usage reports can carry it", "snippet": "{\"name\":\"production\",\"metadata\":{\"referrals_token\":\"{token}\"}}", "lang": "json", "max_tokens": 2, "carries": "token", "who_can_see": "The key's owner and the vendor's staff and systems.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "oauth_state", "layer": "web", "label": "OAuth state", "field": "state", "where": "Inside the state value of an authorization request, next to your own anti-forgery value", "snippet": "state=.{token}", "lang": "text", "max_tokens": 1, "carries": "token", "who_can_see": "The person's browser, the authorization server and the client.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "promo_code", "layer": "commerce", "label": "Promo code", "field": "promo_code", "where": "An existing plain code. It resolves to rf1..", "snippet": "{code}", "lang": "text", "max_tokens": 0, "carries": "code", "who_can_see": "Anyone the code is shared with, and code-sharing sites.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "checkout_attribution", "layer": "commerce", "label": "Checkout protocol", "field": "affiliate_attribution.token", "where": "The affiliate_attribution object of an agentic checkout request. Write-only on the merchant's side, and it must hold no personal data", "snippet": "{\"affiliate_attribution\":{\"provider\":\"referrals.md\",\"token\":\"{token}\",\"touchpoint\":\"last\",\"source\":\"agent\"}}", "lang": "json", "max_tokens": 1, "carries": "token", "who_can_see": "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": false, "as_of": "2026-10", "trust": "Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. Check the protocol's own spec, which can change." }, { "id": "billing_metadata", "layer": "billing", "label": "Billing metadata", "field": "metadata.referrals_token", "where": "Customer, subscription or invoice metadata in your billing system", "snippet": "{\"metadata\":{\"referrals_token\":\"{token}\"}}", "lang": "json", "max_tokens": 2, "max_chars": 500, "carries": "token", "who_can_see": "The vendor's staff and systems, and anyone with access to the billing account.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "crm_field", "layer": "business", "label": "CRM record", "field": "referrals_token, referrals_deal_role", "where": "Fields on an account or opportunity", "snippet": "referrals_token={token}\nreferrals_deal_role=sourced", "lang": "text", "max_tokens": 2, "carries": "token", "who_can_see": "The vendor's sales and partner teams.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "order_form_clause", "layer": "contract", "label": "Order form", "field": "Referral clause", "where": "A line in an order form or statement of work", "snippet": "Referral: `{token}`. The parties named in this order form agree this referral is recorded under that token.", "lang": "markdown", "max_tokens": 1, "carries": "token", "who_can_see": "The parties to the contract.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "x402_extension", "layer": "payment", "label": "402 payment", "field": "extensions[\"builder-code\"]", "where": "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", "snippet": "{\"extensions\":{\"builder-code\":{\"a\":\"{code}\"}}}", "lang": "json", "max_tokens": 0, "carries": "code", "who_can_see": "Anyone, once the payment settles on a public chain.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "erc8021_suffix", "layer": "chain", "label": "Calldata suffix", "field": "ERC-8021 suffix", "where": "An ERC-8021 attribution suffix on a transaction's calldata. Only the code rides, and it resolves to rf1..", "snippet": "codes: [\"{code}\"]", "lang": "text", "max_tokens": 0, "carries": "code", "who_can_see": "Anyone reading the chain.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "chain_memo", "layer": "chain", "label": "Transaction memo", "field": "memo", "where": "A memo field or note on a transfer, on chains that have one", "snippet": "{code}", "lang": "text", "max_tokens": 0, "carries": "code", "who_can_see": "Anyone reading the chain, for good. Never put anything about a person here.", "internal_only": false, "as_of": "2026-10", "trust": "A public claim, equal to an unsigned token. Anyone can copy it, or put it on volume they made." }, { "id": "contract_param", "layer": "chain", "label": "Contract parameter", "field": "referrer", "where": "A referrer or code parameter a smart contract already takes", "snippet": "swap(amountIn, minOut, path, to, \"{code}\")", "lang": "text", "max_tokens": 0, "carries": "code", "who_can_see": "Anyone reading the chain.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "email_header", "layer": "email", "label": "Email header", "field": "Referrals-Token", "where": "A message header on an intro or outbound email", "snippet": "Referrals-Token: {token}", "lang": "text", "max_tokens": 2, "carries": "token", "who_can_see": "Recipients, forwarders and mail systems on the path.", "internal_only": false, "as_of": "2026-10", "trust": "Unsigned, a token proves nothing. Anyone can copy or invent one for a known code. Forwarding keeps or drops it without notice." }, { "id": "code", "layer": "code", "label": "SDK or environment", "field": "REFERRALS_TOKEN, referrals_token", "where": "An environment variable or an argument in code you ship", "snippet": "REFERRALS_TOKEN={token}", "lang": "bash", "max_tokens": 8, "carries": "token", "who_can_see": "Anyone who can read the code or the process's environment.", "internal_only": false, "as_of": "2026-10", "trust": "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." }, { "id": "otel_attr", "layer": "observability", "label": "Trace attribute", "field": "md.referrals.touch_id", "where": "A span attribute. It holds a touch id, never a token", "snippet": "md.referrals.touch_id={touch}", "lang": "text", "max_tokens": 0, "carries": "touch_id", "who_can_see": "Whoever can read your traces.", "internal_only": false, "as_of": "2026-10", "trust": "A touch id alone carries nothing useful to a thief, which is why this is the only trace carrier that can leave your organization." }, { "id": "tracestate", "layer": "observability", "label": "tracestate", "field": "tracestate: referrals=", "where": "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", "snippet": "tracestate: referrals={token}", "lang": "http", "max_tokens": 1, "max_chars": 256, "carries": "token", "who_can_see": "Every service and vendor on the trace, since trace headers forward by design.", "internal_only": true, "as_of": "2026-10", "trust": "Inside one organization only. It MUST be stripped at its boundary. A signed token is over 128 characters, so it goes first under pressure." }, { "id": "baggage", "layer": "observability", "label": "baggage", "field": "baggage: referrals.token=", "where": "A W3C baggage entry", "snippet": "baggage: referrals.token={token}", "lang": "http", "max_tokens": 1, "carries": "token", "who_can_see": "Every service and vendor on the trace, since baggage forwards by design.", "internal_only": true, "as_of": "2026-10", "trust": "Inside one organization only. It MUST be stripped at its boundary." } ], "carrier_note": "These are mappings this format proposes. The owners of those specs have not reviewed or adopted them, and their specs can change. Check them." }