Syndicate Links

x402 Integration Guide

Syndicate Links exposes a pay-per-call x402 endpoint for AI agents. No account. No API key. No subscription. Agents pay $0.01 USDC on Base per call and receive an affiliate tracking link in response.

This guide covers the complete integration flow from first request to settled tracking link.

Endpoint

POST https://api.syndicatelinks.co/affiliate/links
Content-Type: application/json

Payment: $0.01 USDC on Base mainnet (eip155:8453)
Settlement wallet: 0x4808399D80299C7F5330cc99DCee0812dacC6D66
Asset: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)

Authenticated callers with an Authorization header bypass x402 entirely — the payment gate applies only to unauthenticated agent callers.

The x402 Two-Step Flow

x402 is a standard HTTP payment protocol. Every call from an unauthenticated agent follows the same two-step pattern:

Step 1: Request → 402 Challenge

Send a normal POST request without a payment header. The server returns 402 Payment Required with a structured payment challenge:

curl -s -X POST https://api.syndicatelinks.co/affiliate/links \
  -H "Content-Type: application/json" \
  -d '{"programId":"prog_abc123","destinationUrl":"https://merchant.com/product"}'

Response (HTTP 402):

{
  "x402Version": 1,
  "error": "Payment required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "maxAmountRequired": "10000",
      "resource": "https://api.syndicatelinks.co/affiliate/links",
      "description": "Tracking link generation fee",
      "mimeType": "application/json",
      "payTo": "0x4808399D80299C7F5330cc99DCee0812dacC6D66",
      "maxTimeoutSeconds": 120,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}

maxAmountRequired: "10000" is 10,000 atomic USDC units = $0.01 at 6 decimals.

Step 2: Pay → Retry with X-PAYMENT Header

Pay the exact amount on Base mainnet and include the payment proof in your retry:

curl -s -X POST https://api.syndicatelinks.co/affiliate/links \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64-encoded-payment-proof>" \
  -d '{"programId":"prog_abc123","destinationUrl":"https://merchant.com/product"}'

The server verifies your payment via the x402 facilitator and returns the tracking link.

Response (HTTP 201):

{
  "trackingLink": "https://go.syndicatelinks.co/t/abc123xyz",
  "attributionToken": "atxp_7gHkL2mPqRsXvZw9aBcD"
}

Integration with @x402/js

The Coinbase x402 SDK handles the two-step flow automatically:

import { wrapFetchWithPayment } from '@x402/js';
import { createWalletClient, http } from 'viem';
import { base } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(),
});

// Wrap fetch with automatic x402 payment handling
const fetchWithPayment = wrapFetchWithPayment(fetch, walletClient);

// Call the endpoint — SDK handles 402 → pay → retry automatically
const response = await fetchWithPayment(
  'https://api.syndicatelinks.co/affiliate/links',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      programId: 'prog_abc123',
      destinationUrl: 'https://merchant.com/product',
    }),
  }
);

const { trackingLink, attributionToken } = await response.json();

Integration with Python

Using the x402-requests library:

import x402_requests
from eth_account import Account

account = Account.from_key(os.environ["AGENT_PRIVATE_KEY"])

session = x402_requests.Session(account)

response = session.post(
    "https://api.syndicatelinks.co/affiliate/links",
    json={
        "programId": "prog_abc123",
        "destinationUrl": "https://merchant.com/product",
    }
)

data = response.json()
tracking_link = data["trackingLink"]
attribution_token = data["attributionToken"]

Request Body

FieldTypeRequiredDescription
programIdstringYesAffiliate program ID (from your publisher account)
destinationUrlstringYesThe merchant product or page URL to link to
metadataobjectNoOptional key-value metadata for attribution

Attribution Tokens

Every successful call returns an attributionToken — a signed atxp_v1 reference in atxp_{base58_16bytes} format. This token:

  • Encodes your agent's identity, the program, and a unique nonce
  • Can be embedded in the tracking link or carried in downstream x402 payment proofs as an atxp_reference
  • Enables commission attribution even across multi-hop agent workflows

See x402 Attribution Integration for the full SLAT token spec.

Rate Limits

LimitDefaultScope
Per-IP requests per minute60 req/minPer originating IP
Per-program requests per minute120 req/minPer programId in request body

Rate-limited requests return HTTP 429 with a Retry-After header (seconds until the window resets). Log format in Railway: [x402:ratelimit] ip=... merchantId=... ts=...

Service Availability

A kill switch (X402_KILL_SWITCH) allows the endpoint to be taken offline without a redeploy. When active, all callers (authenticated or not) receive HTTP 503 with {"error": "x402 endpoint temporarily disabled"} and a Cache-Control: no-store header. This is an operational control — if you receive a 503, retry after a short delay rather than treating it as a permanent failure.

Machine-Readable Discovery

The x402 payment descriptor is published at:

GET https://api.syndicatelinks.co/.well-known/machine-payments

This returns a JSON descriptor with the x402 block, accepted payment schemes, network, and payTo address. Compatible with any x402-aware agent framework that uses .well-known autodiscovery.

Receipt Logging

Every settled payment generates a structured log line in the API server:

[x402:receipt] txHash=0x... network=eip155:8453 amount=10000 payer=0x... endpoint=POST /affiliate/links ts=2026-04-21T03:11:09.000Z

amount is in atomic USDC units (divide by 1,000,000 for USDC value). This feeds treasury reconciliation at the wallet 0x4808399....