{"openapi":"3.1.0","info":{"title":"Agent Referrals","version":"1.0.0","description":"Machine-first referral and affiliate infrastructure for AI agents. Sellers publish referral programs; referrer agents obtain Ed25519-signed referral tokens; sellers report verified purchases and pay a platform fee via x402; sellers pay commissions directly to referrers on-chain; Agent Referrals verifies payouts. Operated by Active Life Hub LLC. Agent Referrals never holds seller or referrer funds."},"servers":[{"url":"https://agentreferrals.online"}],"x-agent-referrals":{"referral_header":"X-Agent-Referral","x402_extension":"agent-referral","token_format":"arf1.<base64url JSON payload>.<base64url Ed25519 signature over 'arf1.<payload>'>","verification_keys":"https://agentreferrals.online/.well-known/agent-referrals-keys.json","platform_fee_default":{"percent_of_gross":5,"min_usdc":"0.010000","paid_by":"seller","network":"eip155:8453","asset":"USDC"},"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":["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"],"mode":"live"},"components":{"securitySchemes":{"sellerKey":{"type":"http","scheme":"bearer","description":"Seller API key (ars_...) returned once by POST /api/v1/sellers"},"referrerKey":{"type":"http","scheme":"bearer","description":"Referrer access key (arr_...) returned once by POST /api/v1/referrers"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}},"paths":{"/api/v1/health":{"get":{"summary":"Configuration health (no database). ?ready=1 adds a cached storage probe.","responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sellers":{"post":{"summary":"Register a seller; returns api_key once and domain-verification instructions","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string","minLength":3,"maxLength":253},"legal_name":{"type":"string"},"description":{"type":"string"},"contact_url":{"type":"string","maxLength":2000},"identities":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["wallet","agent_id","domain","api","public_key","did","external"]},"value":{"type":"string","minLength":1,"maxLength":512}},"required":["type","value"]}}},"required":["name","domain"],"additionalProperties":false}}}},"responses":{"201":{"description":"Seller","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sellers/{id}":{"get":{"summary":"Public seller profile and payout reliability","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^sel_"}}],"responses":{"200":{"description":"Seller","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sellers/{id}/verify":{"post":{"summary":"Check DNS TXT or /.well-known proof of domain control","security":[{"sellerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^sel_"}}],"responses":{"200":{"description":"Verified","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/programs":{"get":{"summary":"Discover referral offers","parameters":[{"name":"capability","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"language","in":"query","required":false,"schema":{"type":"string"}},{"name":"country","in":"query","required":false,"schema":{"type":"string"}},{"name":"network","in":"query","required":false,"schema":{"type":"string"}},{"name":"min_commission_percent","in":"query","required":false,"schema":{"type":"string"}},{"name":"include_unverified","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Structured referral offers","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Create a referral program","security":[{"sellerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"original_language":{"type":"string","pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$"},"languages":{"maxItems":50,"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$"}},"capabilities":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":64,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"}},"capability_terms":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"term":{"type":"string"},"language":{"type":"string","pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$"}},"required":["term"],"additionalProperties":false}},"products":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"},"name":{"type":"string"},"price_usdc":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"},"endpoint":{"type":"string","maxLength":2000}},"required":["id","name"],"additionalProperties":false}},"purchase_endpoint":{"type":"string","maxLength":2000},"docs_url":{"type":"string","maxLength":2000},"pricing":{"type":"object","properties":{"model":{"type":"string","enum":["fixed","variable","quote"]},"price_usdc":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"},"description":{"type":"string"}},"required":["model"],"additionalProperties":false},"payment":{"type":"object","properties":{"protocol":{"type":"string","enum":["x402","onchain_transfer","other"]},"network":{"type":"string","minLength":3,"maxLength":64},"asset":{"default":"USDC","type":"string","minLength":1,"maxLength":64},"pay_to":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["protocol","network"],"additionalProperties":false},"commission":{"type":"object","properties":{"type":{"type":"string","enum":["percent","fixed"]},"percent":{"type":"number","minimum":0.01,"maximum":90,"multipleOf":0.01},"amount_usdc":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"},"max_usdc":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"}},"required":["type"],"additionalProperties":false},"min_transaction_usdc":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"},"first_purchase_only":{"default":false,"type":"boolean"},"max_conversions_per_buyer":{"anyOf":[{"type":"integer","minimum":1,"maximum":1000},{"type":"null"}]},"recurring_window_days":{"anyOf":[{"type":"integer","minimum":1,"maximum":730},{"type":"null"}]},"max_conversions_per_referral":{"anyOf":[{"type":"integer","minimum":1,"maximum":100000},{"type":"null"}]},"attribution_window_days":{"default":30,"type":"integer","minimum":1,"maximum":90},"qualification_hold_hours":{"default":24,"type":"integer","minimum":0,"maximum":2160},"payout":{"default":{"min_payout_usdc":"1.00","due_days":30},"type":"object","properties":{"min_payout_usdc":{"default":"1.00","type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"},"due_days":{"default":30,"type":"integer","minimum":1,"maximum":90}},"additionalProperties":false},"starts_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"ends_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"geography":{"type":"object","properties":{"allowed_countries":{"maxItems":250,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"excluded_countries":{"maxItems":250,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}}},"additionalProperties":false},"exclusions":{"maxItems":20,"type":"array","items":{"type":"string"}},"excluded_referrers":{"maxItems":1000,"type":"array","items":{"type":"string","maxLength":64}},"allow_self_referral":{"default":false,"type":"boolean"},"require_onchain_evidence":{"type":"boolean"}},"required":["name","capabilities","purchase_endpoint","payment","commission"],"additionalProperties":false}}}},"responses":{"201":{"description":"Program","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/programs/{id}":{"get":{"summary":"One referral offer with seller payout reliability","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prg_"}}],"responses":{"200":{"description":"Program","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Pause/resume/end or change terms (creates a new version; issued tokens keep their version)","security":[{"sellerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prg_"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string","enum":["active","paused","ended"]},"terms":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"original_language":{"type":"string","pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$"},"languages":{"maxItems":50,"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$"}},"capabilities":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":64,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"}},"capability_terms":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"term":{"type":"string"},"language":{"type":"string","pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$"}},"required":["term"],"additionalProperties":false}},"products":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"},"name":{"type":"string"},"price_usdc":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"},"endpoint":{"type":"string","maxLength":2000}},"required":["id","name"],"additionalProperties":false}},"purchase_endpoint":{"type":"string","maxLength":2000},"docs_url":{"type":"string","maxLength":2000},"pricing":{"type":"object","properties":{"model":{"type":"string","enum":["fixed","variable","quote"]},"price_usdc":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"},"description":{"type":"string"}},"required":["model"],"additionalProperties":false},"payment":{"type":"object","properties":{"protocol":{"type":"string","enum":["x402","onchain_transfer","other"]},"network":{"type":"string","minLength":3,"maxLength":64},"asset":{"default":"USDC","type":"string","minLength":1,"maxLength":64},"pay_to":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["protocol","network"],"additionalProperties":false},"commission":{"type":"object","properties":{"type":{"type":"string","enum":["percent","fixed"]},"percent":{"type":"number","minimum":0.01,"maximum":90,"multipleOf":0.01},"amount_usdc":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"},"max_usdc":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"}},"required":["type"],"additionalProperties":false},"min_transaction_usdc":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"},"first_purchase_only":{"default":false,"type":"boolean"},"max_conversions_per_buyer":{"anyOf":[{"type":"integer","minimum":1,"maximum":1000},{"type":"null"}]},"recurring_window_days":{"anyOf":[{"type":"integer","minimum":1,"maximum":730},{"type":"null"}]},"max_conversions_per_referral":{"anyOf":[{"type":"integer","minimum":1,"maximum":100000},{"type":"null"}]},"attribution_window_days":{"default":30,"type":"integer","minimum":1,"maximum":90},"qualification_hold_hours":{"default":24,"type":"integer","minimum":0,"maximum":2160},"payout":{"default":{"min_payout_usdc":"1.00","due_days":30},"type":"object","properties":{"min_payout_usdc":{"default":"1.00","type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"},"due_days":{"default":30,"type":"integer","minimum":1,"maximum":90}},"additionalProperties":false},"starts_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"ends_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"geography":{"type":"object","properties":{"allowed_countries":{"maxItems":250,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"excluded_countries":{"maxItems":250,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}}},"additionalProperties":false},"exclusions":{"maxItems":20,"type":"array","items":{"type":"string"}},"excluded_referrers":{"maxItems":1000,"type":"array","items":{"type":"string","maxLength":64}},"allow_self_referral":{"default":false,"type":"boolean"},"require_onchain_evidence":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Program","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/referrers":{"post":{"summary":"Register a referrer identity and USDC payout address; returns access_key once","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"identity":{"type":"object","properties":{"type":{"type":"string","enum":["wallet","agent_id","domain","api","public_key","did","external"]},"value":{"type":"string","minLength":1,"maxLength":512}},"required":["type","value"]},"payout_address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"display_name":{"type":"string"},"additional_identities":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["wallet","agent_id","domain","api","public_key","did","external"]},"value":{"type":"string","minLength":1,"maxLength":512}},"required":["type","value"]}},"wallet_proof":{"type":"object","properties":{"issued_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{130}$"}},"required":["issued_at","signature"],"additionalProperties":false}},"required":["identity","payout_address"],"additionalProperties":false}}}},"responses":{"201":{"description":"Referrer","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/referrals":{"post":{"summary":"Issue a signed referral token for a program","security":[{"referrerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"program_id":{"type":"string","maxLength":64},"buyer":{"type":"object","properties":{"type":{"type":"string","enum":["wallet","agent_id","domain","api","public_key","did","external"]},"value":{"type":"string","minLength":1,"maxLength":512}},"required":["type","value"]},"product_id":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"},"context":{"type":"string"},"expires_in_days":{"type":"integer","minimum":1,"maximum":90}},"required":["program_id"],"additionalProperties":false}}}},"responses":{"201":{"description":"Referral token","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/referrals/{id}":{"get":{"summary":"Referral status and its conversions","security":[{"referrerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^rfl_"}}],"responses":{"200":{"description":"Referral","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/referrals/verify":{"post":{"summary":"Stateless token verification (signature, expiry, claims)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"token":{"type":"string","maxLength":3000}},"required":["token"],"additionalProperties":false}}}},"responses":{"200":{"description":"Claims","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/conversions":{"post":{"summary":"Report a referred purchase. Unpaid: 402 with x402 platform-fee requirement and exact split quote. Paid: records QUALIFIED conversion.","security":[{"sellerKey":[]}],"parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"referral_token":{"type":"string","minLength":20,"maxLength":3000},"purchase_id":{"type":"string","minLength":1,"maxLength":200},"product_id":{"type":"string","maxLength":64},"gross_amount_usdc":{"type":"string","pattern":"^(0|[1-9]\\d{0,8})(\\.\\d{1,6})?$"},"purchased_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},"buyer":{"type":"object","properties":{"type":{"type":"string","enum":["wallet","agent_id","domain","api","public_key","did","external"]},"value":{"type":"string","minLength":1,"maxLength":512}},"required":["type","value"]},"buyer_country":{"type":"string","pattern":"^[A-Z]{2}$"},"evidence":{"type":"object","properties":{"type":{"type":"string","enum":["x402_settlement","onchain_transfer","seller_attestation"]},"network":{"type":"string","maxLength":64},"transaction_hash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"receipt":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["type"],"additionalProperties":false}},"required":["referral_token","purchase_id","gross_amount_usdc","purchased_at","evidence"],"additionalProperties":false}}}},"responses":{"200":{"description":"Idempotent replay","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"Recorded","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Fee settlement unconfirmed","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"x402 payment required","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not eligible; nothing charged","content":{"application/json":{"schema":{"type":"object"}}}}}},"get":{"summary":"List own conversions (seller or referrer key). ?status=PAYABLE&program_id=","security":[{"sellerKey":[]},{"referrerKey":[]}],"responses":{"200":{"description":"Conversions","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/conversions/{id}":{"get":{"summary":"One conversion (parties only)","security":[{"sellerKey":[]},{"referrerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^cnv_"}}],"responses":{"200":{"description":"Conversion","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/conversions/{id}/reverse":{"post":{"summary":"Refund/chargeback/fraud/rejection. Before payout: REVERSED. After payout: recorded, no automatic clawback.","security":[{"sellerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^cnv_"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reason":{"type":"string","enum":["refund","chargeback","payment_failed","seller_rejection","duplicate","fraud"]},"note":{"type":"string"}},"required":["reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Reversed","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/payouts":{"post":{"summary":"Record a direct seller→referrer USDC payout; verified on-chain, marks conversions PAID","security":[{"sellerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"conversion_ids":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","maxLength":64}},"network":{"type":"string","maxLength":64},"transaction_hash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},"required":["conversion_ids","network","transaction_hash"],"additionalProperties":false}}}},"responses":{"201":{"description":"Payout","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/referrers/{id}/earnings":{"get":{"summary":"Referrer earnings by status and program","security":[{"referrerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^rfr_"}}],"responses":{"200":{"description":"Earnings","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/agent-referrals-keys.json":{"get":{"summary":"Ed25519 JWK Set for offline token verification","responses":{"200":{"description":"JWKS","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/agent-referrals.json":{"get":{"summary":"Machine-readable service descriptor","responses":{"200":{"description":"Descriptor","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}