x402 & Agent Attribution

The atxp_reference Standard

atxp_reference is the canonical attribution identifier in Syndicate Links. It is a protocol-agnostic, top-level concept — not a footnote to any specific payment protocol or transport mechanism.

When an AI agent drives a conversion, the system needs a durable, machine-readable way to credit the correct affiliate regardless of how the payment is settled. atxp_reference is that identifier. It binds the conversion event to the affiliate account that initiated it, survives protocol boundaries, and can be carried through any payment flow — direct API, Stripe MPP, ACP, or x402 — without modification.

Format

atxp_{base58_16bytes}

atxp_ is a literal prefix identifying the token type. The remainder is 16 bytes of cryptographic random data encoded in base58. The result is a 22-character, URL-safe, case-sensitive string.

Example:

atxp_7gHkL2mPqRsXvZw9aBcD

Scope and Lifecycle

atxp_reference is not a session token, not a cookie, and not a redirect parameter. It is a post-conversion receipt identifier, used to correlate attribution records across systems.

x402 and Agent Commerce

x402 is an emerging payment protocol for HTTP-native micropayments. An x402-capable server returns a 402 Payment Required response with a machine-readable payment requirement, and a compliant client fulfills the payment before retrying the request. The full cycle is:

1. Client → Server:   GET /resource
2. Server → Client:   402 Payment Required + X-Payment-Requirements header
3. Client → Server:   GET /resource + X-Payment header (payment proof)
4. Server → Client:   200 OK + X-Payment-Response header (receipt)

AI agents are the primary beneficiaries of x402 — they can settle payments autonomously without user involvement. This makes x402 a natural fit for agentic commerce, and agentic commerce is exactly where Syndicate Links attribution applies.

Carrying Attribution Through x402 — Option A (Recommended)

The x402 spec defines X-Payment-Requirements and X-Payment headers. It does not currently define a field for referral or affiliate attribution in either the payment requirement or the payment response.

Until the spec includes a first-class attribution field (see Spec Contribution Flag below), the recommended approach is Option A: pre-402 X-SL-Attribution header.

How It Works

The agent sends attribution metadata in the initial request, before the 402 response. The X-SL-Attribution header carries the atxp_reference token directly in the HTTP request that triggers the payment flow.

GET /resource
X-SL-Attribution: atxp_7gHkL2mPqRsXvZw9aBcD

If the server returns 402, the client re-sends the same header alongside X-Payment:

GET /resource
X-Payment: <payment-proof>
X-SL-Attribution: atxp_7gHkL2mPqRsXvZw9aBcD

The merchant's server reads X-SL-Attribution from the fulfilled request and forwards it to Syndicate Links at settlement time, crediting the attribution event.

Why Option A

Option A requires no changes to the x402 protocol. It is additive — servers that don't recognize X-SL-Attribution ignore it; servers that do can forward it to Syndicate Links for commission recording.

Implementation

Agent side — minting and sending:

import crypto from 'crypto';

// 1. Mint the atxp_reference (done once per conversion event)
const atxpReference = await mintAtxpReference({
  affiliateId: process.env.SL_AFFILIATE_ID,
  programId: 'prog_01HABC9876543210',
  trackingCode: 'AGENTSPRING2026',
  secret: process.env.SL_AGENT_TOKEN_SECRET,
});

// 2. Include X-SL-Attribution on the initial request
const res = await fetch('https://merchant.example.com/resource', {
  headers: {
    'X-SL-Attribution': atxpReference,
  },
});

// 3. If 402, fulfill payment and retry with the same header
if (res.status === 402) {
  const paymentProof = await fulfillPayment(res.headers.get('X-Payment-Requirements'));

  const finalRes = await fetch('https://merchant.example.com/resource', {
    headers: {
      'X-Payment': paymentProof,
      'X-SL-Attribution': atxpReference,
    },
  });
}

Merchant side — reading and forwarding:

// Express / Hono / any HTTP server
app.use(async (req, res, next) => {
  const atxpRef = req.headers['x-sl-attribution'];
  if (atxpRef) {
    // Forward to Syndicate Links after payment is confirmed
    req.slAttribution = atxpRef;
  }
  next();
});

// After payment verification succeeds:
await fetch('https://api.syndicatelinks.co/v1/track/agent-attribution', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SL_MERCHANT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    attribution_token: req.slAttribution,
    order_id: paymentReceipt.id,
    amount: paymentReceipt.amount,
    currency: paymentReceipt.currency,
  }),
});

The attribution_token field maps directly to the atxp_reference value from the header. No additional parsing is required.

x402 Spec Contribution Flag

The x402 protocol's PAYMENT-RESPONSE object (returned in the X-Payment-Response header after a successful payment) currently carries receipt metadata: transaction ID, amount, and timestamp. It does not include a field for referral or affiliate attribution.

Syndicate Links is the first to propose adding a referral/attribution field to PAYMENT-RESPONSE.

The proposed extension:

{
  "txid": "0xabc123...",
  "amount": "0.001",
  "currency": "USDC",
  "network": "base",
  "timestamp": 1743638400,
  "referral": {
    "ref": "atxp_7gHkL2mPqRsXvZw9aBcD",
    "provider": "syndicatelinks"
  }
}

Adding referral to PAYMENT-RESPONSE would make attribution first-class in x402 — any x402-compatible client and server could carry attribution data without a custom header, with no ambiguity about where to put it.

Until this field is standardized, Option A (X-SL-Attribution header) is the practical path. If the x402 working group adopts a referral field — in any form — the atxp_reference format is designed to be the value that goes there.

The Syndicate Links MCP server (npx syndicate-links-mcp) already emits atxp_reference tokens in a format compatible with this proposed field. No changes to agent-side tooling will be needed if the field is adopted.

Internal Testing Note — Facilitator DNS

When testing x402 integration from a hosted environment (Railway, Render, Fly.io, etc.), note that outbound DNS to facilitator.x402.org may be blocked at the network layer.

What this means in practice:

• The 402 challenge still fires correctly — the payment requirement body is hardcoded on the server side and does not require a facilitator round-trip.
• Facilitator verification (validating the X-PAYMENT proof on the agent's retry) runs from the agent's network, not the server's. In production, agent clients call the facilitator directly. The server only needs to call the facilitator if it performs its own on-chain receipt check.
• If you are running curl-based smoke tests from inside the hosted environment with a real X-PAYMENT header, verification will fail with a 500 if your network blocks facilitator.x402.org. This is an environment constraint, not a protocol bug.

Workaround for internal testing:

Test the 402 challenge shape without a payment proof:

curl -s -X POST https://api.syndicatelinks.co/affiliate/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
# → HTTP 402 with well-formed accepts[] body

Test end-to-end (402 → payment → 200) from a machine with unrestricted outbound DNS, or use a real agent client — the agent's facilitator call goes from the agent's network and is not subject to the server's egress restrictions.

Related Resources

• What Is Agent Attribution? — /docs/what-is-agent-attribution — the explainer: what agent attribution is, why cookies fail, FAQ
• How Agent Attribution Works — /docs/agent-attribution-spec — full two-layer auth, slat_v1_ token format, nonce replay, and error reference
• ACP Attribution — /docs/acp-attribution — ai_referral events and ai_surface context in ACP flows
• Getting Started — /docs/getting-started
• MCP Server — npx syndicate-links-mcp — 7 attribution and affiliate tools for Claude Desktop or any MCP-compatible agent runtime