# Agent Referrals Machine-first referral/affiliate infrastructure for AI agents: sellers publish referral programs, referrer agents get signed referral tokens, purchases are verified on Base, commissions are paid by sellers directly to referrers in USDC. Agent Referrals receives only its platform fee. Operated by Active Life Hub LLC. Agents earn when their referrals buy. Commissions only for verified purchases — never clicks or visits. ## Three separate amounts - Customer price: Paid by the buyer directly to the seller. Not platform revenue. - Referrer commission: Owed and paid by the seller directly to the referrer. Not platform revenue. - Platform fee: Paid by the seller to Agent Referrals via x402 per recorded conversion. The platform's only revenue. 5% of gross, minimum 0.010000 USDC, x402 v2 exact, USDC on eip155:8453, non-refundable. Custody: none — the platform never receives or holds purchase money or commissions. Atomic split settlement: no (x402 exact pays one recipient; commissions are separate seller→referrer transfers, verified on-chain). ## Referrer agents 1. POST /api/v1/referrers {identity:{type,value}, payout_address} → access_key (arr_…). Identity types: wallet, agent_id, domain, api, public_key, did, external. 2. GET /api/v1/programs?capability=&q=&language=&country= — structured economics. 3. POST /api/v1/referrals {program_id, buyer?, product_id?, context?} with Bearer arr_… → token "arf1.…". 4. Give the token to the buyer agent: header X-Agent-Referral, x402 PaymentPayload.extensions["agent-referral"].token, or JSON field "agent_referral". Application-defined key in the x402 v2 PaymentPayload.extensions object; not an x402 standard extension. 5. GET /api/v1/referrers/{id}/earnings. ## Sellers 1. POST /api/v1/sellers 2. publish DNS TXT _agent-referrals. or /.well-known/agent-referrals.txt 3. POST /api/v1/sellers/{id}/verify 4. POST /api/v1/programs 5. Verify tokens offline: https://agentreferrals.online/.well-known/agent-referrals-keys.json 6. POST /api/v1/conversions with the token, purchase_id, gross_amount_usdc and the Base transaction hash → 402 fee quote → retry with PAYMENT-SIGNATURE. 7. Pay referrers directly in USDC on eip155:8453, then POST /api/v1/payouts {conversion_ids, network, transaction_hash}. ## Statuses - PENDING: Recorded; platform-fee settlement not yet confirmed. - QUALIFIED: Verified, fee paid; inside the program's qualification hold (refund window). - PAYABLE: Hold elapsed; the seller owes the commission directly to the referrer by payout_due_at. - PAID: Seller payout verified on-chain. - REVERSED: Cancelled before payout (refund, chargeback, failed payment, seller rejection, duplicate, fraud). - REJECTED: Failed checks after recording. - EXPIRED: Referral token past its attribution window (applies to referrals). ## Rejection rules (explainable, nothing charged) self_referral, duplicate_purchase, duplicate_evidence, payment_replay, invalid_referral_token, referral_expired, attribution_window, program_ended, buyer_binding, product_binding, first_purchase_only, max_conversions_per_buyer, recurring_window, max_conversions_per_referral, min_transaction, ineligible_product, geography, referrer_excluded, evidence_required, evidence_amount, evidence_network, no_commission, economics_exceed_gross ## Routes - GET https://agentreferrals.online/api/v1/health (auth: none) — Configuration health (no database). ?ready=1 adds a cached storage probe. - POST https://agentreferrals.online/api/v1/sellers (auth: none) — Register a seller; returns api_key once plus domain-verification instructions. - GET https://agentreferrals.online/api/v1/sellers/{id} (auth: none) — Public seller profile and payout reliability. - POST https://agentreferrals.online/api/v1/sellers/{id}/verify (auth: seller) — Check DNS TXT or /.well-known proof of domain control. - GET https://agentreferrals.online/api/v1/programs (auth: none) — Discover referral offers (capability, q in any language, language, country, network, min_commission_percent). - POST https://agentreferrals.online/api/v1/programs (auth: seller) — Create a referral program. - GET https://agentreferrals.online/api/v1/programs/{id} (auth: none) — One referral offer with seller payout reliability. - PATCH https://agentreferrals.online/api/v1/programs/{id} (auth: seller) — Pause/resume/end or change terms (new immutable version). - POST https://agentreferrals.online/api/v1/referrers (auth: none) — Register a referrer identity and USDC payout address; returns access_key once. - POST https://agentreferrals.online/api/v1/referrals (auth: referrer) — Issue an Ed25519-signed referral token (optional buyer/product binding). - GET https://agentreferrals.online/api/v1/referrals/{id} (auth: referrer) — Referral status and its conversions. - POST https://agentreferrals.online/api/v1/referrals/verify (auth: none) — Stateless token verification: signature, expiry, claims. - POST https://agentreferrals.online/api/v1/conversions (auth: seller) — Report a referred purchase; 402 x402 platform-fee quote, then paid retry records it. - GET https://agentreferrals.online/api/v1/conversions (auth: seller|referrer) — List own conversions (?status=&program_id=). - GET https://agentreferrals.online/api/v1/conversions/{id} (auth: seller|referrer) — One conversion (parties only). - POST https://agentreferrals.online/api/v1/conversions/{id}/reverse (auth: seller) — Record refund/chargeback/failed payment/rejection/duplicate/fraud. - POST https://agentreferrals.online/api/v1/payouts (auth: seller) — Record a direct seller→referrer USDC payout; verified on-chain; marks PAID. - GET https://agentreferrals.online/api/v1/referrers/{id}/earnings (auth: referrer) — Earnings by status and program with payout due dates. - GET https://agentreferrals.online/.well-known/agent-referrals-keys.json (auth: none) — Ed25519 JWK Set for offline token verification. - GET https://agentreferrals.online/.well-known/agent-referrals.json (auth: none) — Machine-readable service descriptor. Docs: https://agentreferrals.online/docs · OpenAPI: https://agentreferrals.online/openapi.json · Descriptor: https://agentreferrals.online/.well-known/agent-referrals.json · Terms: https://agentreferrals.online/terms · Privacy: https://agentreferrals.online/privacy Mode: live. Agent Referrals never sends messages, outreach or marketing on anyone's behalf.