Agent Referrals API

Three amounts — never confused

Roles and keys

1. Seller: register and verify your domain

POST https://agentreferrals.online/api/v1/sellers
{"name":"Vendor Finder","domain":"vendorfinder.online","legal_name":"Active Life Hub LLC"}

→ 201 {"seller":{"id":"sel_…"},"api_key":"ars_…","verification":{"options":[
  {"method":"dns_txt","name":"_agent-referrals.vendorfinder.online","value":"agent-referrals-verification=…"},
  {"method":"well_known","url":"https://vendorfinder.online/.well-known/agent-referrals.txt", …}]}}

POST https://agentreferrals.online/api/v1/sellers/sel_…/verify
Authorization: Bearer ars_…

Programs are discoverable and can issue tokens only after verification. All URLs in a program must be on the verified domain or its subdomains.

2. Seller: publish a program

POST https://agentreferrals.online/api/v1/programs
Authorization: Bearer ars_…
{
  "name": "Vendor Finder",
  "description": "Verified supplier discovery for AI agents. Поиск поставщиков. 仕入先検索.",
  "original_language": "en",
  "languages": [
    "en",
    "es",
    "ru",
    "ja",
    "zh"
  ],
  "capabilities": [
    "supplier-discovery"
  ],
  "capability_terms": [
    {
      "term": "поиск поставщиков",
      "language": "ru"
    },
    {
      "term": "仕入先検索",
      "language": "ja"
    }
  ],
  "purchase_endpoint": "https://vendorfinder.online/api/v1/search",
  "docs_url": "https://vendorfinder.online/docs",
  "pricing": {
    "model": "fixed",
    "price_usdc": "0.46"
  },
  "payment": {
    "protocol": "x402",
    "network": "eip155:8453",
    "asset": "USDC",
    "pay_to": "0xSELLER_RECEIVING_ADDRESS"
  },
  "commission": {
    "type": "percent",
    "percent": 10,
    "max_usdc": "5.00"
  },
  "first_purchase_only": false,
  "attribution_window_days": 30,
  "qualification_hold_hours": 24,
  "payout": {
    "min_payout_usdc": "1.00",
    "due_days": 30
  },
  "allow_self_referral": false
}

Optional controls: fixed commissions (amount_usdc), max_usdc, min_transaction_usdc, first_purchase_only, max_conversions_per_buyer, recurring_window_days, max_conversions_per_referral, products (eligible products), geography.allowed_countries / excluded_countries, starts_at / ends_at, exclusions, excluded_referrers, allow_self_referral (default false), require_onchain_evidence (default true for USDC on Base). PATCH /api/v1/programs/{id} pauses, ends or changes terms; changed terms get a new version and existing tokens keep the version they were issued under.

3. Referrer: discover offers and get a token

GET https://agentreferrals.online/api/v1/programs?capability=supplier-discovery
GET https://agentreferrals.online/api/v1/programs?q=поиск%20поставщиков&language=ru&country=JP

POST https://agentreferrals.online/api/v1/referrers
{"identity":{"type":"agent_id","value":"eip155:8453:0xREGISTRY:42"},
 "payout_address":"0xYOUR_BASE_USDC_ADDRESS"}
→ 201 {"referrer":{"id":"rfr_…"},"access_key":"arr_…"}

POST https://agentreferrals.online/api/v1/referrals
Authorization: Bearer arr_…
{"program_id":"prg_…","context":"conversation 8812"}
→ 201 {"token":"arf1.eyJ2Ijox….<sig>","referral":{"expires_at":"…"},"economics":{…}}

Identity types: wallet, agent_id, domain, api, public_key, did, external. Optionally prove payout-address control with wallet_proof: {issued_at, signature} — an EOA personal_sign of the message Agent Referrals: I control <address> and accept referral commission payouts to it for <type>:<value>. Issued at <issued_at>. Identity fields are identifiers, not legal identity verification. Optional buyer binds a token to one buyer identity.

4. Buyer: purchase with the token

POST https://vendorfinder.online/api/v1/search
X-Agent-Referral: arf1.…
PAYMENT-SIGNATURE: <x402 payment>

# or inside the x402 PaymentPayload:
"extensions": {"agent-referral": {"token": "arf1.…"}}

agent-referral is an application-defined key inside the x402 v2 PaymentPayload.extensions object — not an x402 standard extension. Sellers may also advertise referral support in their own 402 extensions. Tokens may be bound to one buyer (buyer) and/or one product (product_id) at issuance.

Sellers verify tokens offline with the Ed25519 keys at /.well-known/agent-referrals-keys.json (signature over the ASCII string arf1.<payload>), or call POST /api/v1/referrals/verify.

5. Seller: report the purchase and pay the platform fee

POST https://agentreferrals.online/api/v1/conversions
Authorization: Bearer ars_…
{"referral_token":"arf1.…","purchase_id":"order-1042","gross_amount_usdc":"0.46",
 "purchased_at":"2026-10-01T12:00:00Z","buyer":{"type":"wallet","value":"0xBUYER"},
 "evidence":{"type":"x402_settlement","network":"eip155:8453","transaction_hash":"0x…"}}

→ 402 {"accepts":[{…x402 exact USDC requirement for the fee…}],
       "quote":{"gross_usdc":"0.460000","referrer_commission_usdc":"0.046000",
                "platform_fee_usdc":"0.023000","seller_net_usdc":"0.391000"}}
# retry the identical request with PAYMENT-SIGNATURE
→ 201 {"conversion":{"id":"cnv_…","status":"QUALIFIED","evidence":{"level":"onchain_verified"}}}

We read the transaction from Base and require a USDC transfer of at least the gross amount to the program's pay_to, inside the token's attribution window (block time). Ineligible purchases return 422 with named rules and are never charged. Retrying the same purchase_id never double-charges. Report within 30 days after the token's expiry. Token expiry never extends past the program's ends_at; after a seller ends a program, purchases made later do not qualify.

6. Payout: seller pays the referrer directly

GET https://agentreferrals.online/api/v1/conversions?status=PAYABLE      (seller key)
# send USDC on Base to the referrer's payout_address, then:
POST https://agentreferrals.online/api/v1/payouts
Authorization: Bearer ars_…
{"conversion_ids":["cnv_…","cnv_…"],"network":"eip155:8453","transaction_hash":"0x…"}
→ 201 {"payout":{"amount_usdc":"0.092000","verification":"onchain_usdc_transfer"}}

Batch many conversions into one transfer. A payout is expected once payable commissions reach the program's min_payout_usdc, and in every case by each conversion's payout_due_at — the minimum never defers a commission indefinitely. Overdue commissions are shown publicly on the seller's program.

Statuses

On-chain payouts cannot be reversed. A refund reported after payout is recorded on the conversion (reversal.after_payment: true) and stays PAID; any recovery is between seller and referrer. The platform fee is not refunded.

Earnings

GET https://agentreferrals.online/api/v1/referrers/rfr_…/earnings
Authorization: Bearer arr_…

Anti-abuse rules

self_referral (buyer or payer matches the referrer; referrer is the seller or pays to the seller's address) unless the program sets allow_self_referral; duplicate_purchase; duplicate_evidence (one transaction, one conversion); payment_replay; token signature and seller ownership; buyer_binding; first_purchase_only / per-buyer and per-referral caps; attribution window by block time. Rules are explainable and report the exact reason.

Languages

All text is Unicode and stored as written. Add capability_terms in any language; discovery matches them without machine translation. Language and geography are independent filters.

Route reference

Errors

{"error":{"code","message","details"}}. 400 invalid_input / invalid_referral_token, 401 unauthorized, 402 payment_required / invalid_payment, 403 forbidden / referrer_excluded, 404 not_found, 409 duplicate_* / evidence_not_found / program_inactive / not_payable, 422 conversion_not_eligible / self_referral / payout_insufficient, 429 rate_limited, 503 not_configured / payments_not_configured / chain_unavailable.