{"openapi":"3.1.0","info":{"title":"FRENT Agent Payments API","version":"2.0.0","description":"Create idempotent, non-custodial USDC payment intents for hosted checkout or x402 v2. x402 activation is fail-closed until facilitator and fee collection readiness are configured."},"servers":[{"url":"https:\/\/frent.tech\/api\/agent\/v1"}],"security":[{"bearerAuth":[]}],"paths":{"\/capabilities":{"get":{"operationId":"getFrentCapabilities","summary":"Discover FRENT agent payment capabilities","security":[],"responses":{"200":{"$ref":"#\/components\/responses\/Capabilities"}}}},"\/connection":{"get":{"operationId":"getFrentMerchantConnection","summary":"Inspect the authenticated merchant connection","responses":{"200":{"$ref":"#\/components\/responses\/Connection"}}}},"\/oauth\/device\/code":{"post":{"operationId":"startFrentDeviceAuthorization","summary":"Start human-approved agent authorization","description":"Implements the OAuth 2.0 Device Authorization Grant. The merchant enters the returned user code on FRENT, connects their wallet, and confirms requested contract deployments.","security":[],"requestBody":{"required":true,"content":{"application\/x-www-form-urlencoded":{"schema":{"type":"object","required":["client_id","agent_name","site_url","networks"],"properties":{"client_id":{"type":"string","format":"uri"},"scope":{"type":"string","default":"merchant:read networks:read payments:create payments:read"},"agent_name":{"type":"string","maxLength":120},"agent_provider":{"type":["string","null"],"maxLength":80},"agent_identifier":{"type":["string","null"],"maxLength":191},"site_url":{"type":"string","format":"uri"},"networks":{"type":"array","minItems":1,"maxItems":2,"uniqueItems":true,"items":{"type":"string","enum":["base-mainnet","polygon-mainnet"]}},"merchant_name":{"type":["string","null"],"maxLength":120}}}}}},"responses":{"200":{"description":"Device and user codes with the human verification URL."},"422":{"$ref":"#\/components\/responses\/Error"}}}},"\/oauth\/token":{"post":{"operationId":"exchangeFrentOAuthToken","summary":"Exchange a device code or rotate a refresh token","security":[],"requestBody":{"required":true,"content":{"application\/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","client_id"],"properties":{"grant_type":{"type":"string","enum":["urn:ietf:params:oauth:grant-type:device_code","refresh_token"]},"client_id":{"type":"string","format":"uri"},"device_code":{"type":"string"},"refresh_token":{"type":"string"}}}}}},"responses":{"200":{"description":"Short-lived access token and rotating refresh token."},"400":{"$ref":"#\/components\/responses\/OAuthError"}}}},"\/onboarding-sessions":{"post":{"operationId":"createFrentAgentOnboarding","summary":"Prepare a merchant wallet and contract onboarding handoff","description":"Returns a human-only frent.tech URL and a separate bearer token for status polling. The agent never receives wallet signing authority.","security":[],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","additionalProperties":false,"required":["agent_name","site_url","networks"],"properties":{"agent_name":{"type":"string","maxLength":120},"agent_provider":{"type":["string","null"],"maxLength":80},"agent_identifier":{"type":["string","null"],"maxLength":191},"site_url":{"type":"string","format":"uri"},"networks":{"type":"array","minItems":1,"maxItems":2,"uniqueItems":true,"items":{"type":"string","enum":["base-mainnet","polygon-mainnet"]}},"merchant_name":{"type":["string","null"],"maxLength":120}}}}}},"responses":{"201":{"$ref":"#\/components\/responses\/Onboarding"},"422":{"$ref":"#\/components\/responses\/Error"}}}},"\/onboarding-sessions\/{onboarding}":{"get":{"operationId":"getFrentAgentOnboarding","summary":"Poll merchant wallet and contract onboarding progress","description":"Use the status_token returned when the onboarding session was created. The scoped Agent API key is returned once, after every requested contract is verified.","security":[{"onboardingStatusToken":[]}],"parameters":[{"name":"onboarding","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"$ref":"#\/components\/responses\/Onboarding"},"401":{"$ref":"#\/components\/responses\/Error"}}}},"\/networks":{"get":{"operationId":"listFrentMerchantNetworks","summary":"List merchant networks ready to receive payments","responses":{"200":{"$ref":"#\/components\/responses\/Networks"}}}},"\/payment-intents":{"post":{"operationId":"createFrentPaymentIntent","summary":"Create an idempotent hosted payment intent","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":191}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","additionalProperties":false,"required":["amount_minor","reference"],"properties":{"amount_minor":{"type":"integer","minimum":100,"maximum":100000,"description":"Amount in USD minor units."},"currency":{"type":"string","enum":["USD"],"default":"USD"},"reference":{"type":"string","maxLength":191},"description":{"type":["string","null"],"maxLength":500},"network":{"type":["string","null"],"enum":["base-mainnet","polygon-mainnet",null]},"return_url":{"type":["string","null"],"format":"uri","description":"Optional. Must match the API key trusted origin."}}}}}},"responses":{"201":{"$ref":"#\/components\/responses\/PaymentIntent"},"409":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"}}}},"\/payment-intents\/{payment}":{"get":{"operationId":"getFrentPaymentIntent","summary":"Get the current state of a payment intent","parameters":[{"name":"payment","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"$ref":"#\/components\/responses\/PaymentIntent"},"404":{"$ref":"#\/components\/responses\/Error"}}}},"\/x402\/payment-requests":{"post":{"operationId":"createFrentX402Payment","summary":"Create an x402 v2 USDC payment resource","description":"Creates an exact EIP-3009 payment resource. The returned resource_url answers with HTTP 402 and PAYMENT-REQUIRED until a compatible payer signs and retries with PAYMENT-SIGNATURE.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":191}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","additionalProperties":false,"required":["amount","reference"],"properties":{"amount":{"type":"string","pattern":"^\\d{1,7}(?:\\.\\d{1,6})?$","example":"0.20"},"reference":{"type":"string","maxLength":191},"description":{"type":["string","null"],"maxLength":500},"network":{"type":["string","null"],"enum":["base-mainnet","polygon-mainnet",null]}}}}}},"responses":{"201":{"$ref":"#\/components\/responses\/X402Payment"},"409":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"503":{"$ref":"#\/components\/responses\/Error"}}}},"\/x402\/payment-requests\/{payment}":{"get":{"operationId":"getFrentX402Payment","summary":"Get x402 verification, settlement, receipt and fee status","parameters":[{"name":"payment","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"$ref":"#\/components\/responses\/X402Payment"},"404":{"$ref":"#\/components\/responses\/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"OAuth access token or legacy FRENT API key","description":"Use OAuth device authorization for new agent integrations. Access tokens expire after one hour."},"onboardingStatusToken":{"type":"http","scheme":"bearer","bearerFormat":"FRENT onboarding status token"}},"schemas":{"PaymentIntent":{"type":"object","required":["id","status","amount_minor","amount_atomic","fee_atomic","merchant_net_after_fee_atomic","pricing","currency","network","settlement","checkout_url","expires_at"],"properties":{"id":{"type":"string","format":"uuid"},"payment_code":{"type":["string","null"]},"status":{"type":"string","enum":["pending","submitted","paid","failed","expired","cancelled"]},"reference":{"type":["string","null"]},"description":{"type":["string","null"]},"amount_minor":{"type":"integer","minimum":100,"maximum":100000,"description":"Amount in USD minor units."},"fee_minor":{"type":"integer","deprecated":true,"description":"Whole-cent compatibility projection. Use fee_atomic for exact settlement."},"net_minor":{"type":"integer","deprecated":true,"description":"Whole-cent compatibility projection. Use merchant_net_after_fee_atomic for exact settlement."},"amount_atomic":{"type":"string","description":"Gross USDC in six-decimal atomic units."},"fee_atomic":{"type":"string","description":"Exact FRENT fee in six-decimal atomic units."},"merchant_net_after_fee_atomic":{"type":"string","description":"Exact merchant settlement in six-decimal atomic units."},"fee_usdc":{"type":"string"},"merchant_net_after_fee_usdc":{"type":"string"},"pricing":{"type":"object","description":"The same deterministic fee model used by POS, API, MCP and x402.","required":["fee_bps","minimum_fee_atomic","maximum_fee_atomic","fee_atomic","merchant_net_after_fee_atomic"],"properties":{"fee_bps":{"type":"integer","const":50},"minimum_fee_atomic":{"type":"string","const":"1000"},"maximum_fee_atomic":{"type":"string","const":"100000"},"fee_atomic":{"type":"string"},"fee_usdc":{"type":"string"},"merchant_net_after_fee_atomic":{"type":"string"},"merchant_net_after_fee_usdc":{"type":"string"}}},"currency":{"type":"string"},"network":{"$ref":"#\/components\/schemas\/Network"},"settlement":{"$ref":"#\/components\/schemas\/Settlement"},"checkout_url":{"type":"string","format":"uri"},"status_api_url":{"type":"string","format":"uri"},"public_status_url":{"type":"string","format":"uri"},"receipt_url":{"type":["string","null"],"format":"uri"},"explorer_url":{"type":["string","null"],"format":"uri"},"payer_wallet":{"type":["string","null"]},"transaction_hash":{"type":["string","null"]},"failure":{"type":["object","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"}}},"Network":{"type":"object","required":["key","name","chain_id","payment_asset","payment_contract"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"chain_id":{"type":"integer"},"native_currency":{"type":["string","null"]},"payment_asset":{"type":"object"},"payment_contract":{"type":["string","null"]}}},"Settlement":{"type":"object","required":["mode","custodial","human_wallet_confirmation_required"],"properties":{"mode":{"type":"string","const":"hosted_checkout"},"custodial":{"type":"boolean","const":false},"human_wallet_confirmation_required":{"type":"boolean","const":true}}},"X402Payment":{"type":"object","required":["id","status","protocol","x402_version","network","asset","pay_to","amount_atomic","pricing","resource_url"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","verifying","settling","settlement_pending","paid","failed","expired"]},"protocol":{"type":"string","const":"x402"},"x402_version":{"type":"integer","const":2},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string"},"pay_to":{"type":"string"},"amount_atomic":{"type":"string","description":"Gross USDC amount in six-decimal atomic units."},"pricing":{"type":"object","description":"Deterministic FRENT fee and collection state.","required":["fee_bps","minimum_fee_atomic","maximum_fee_atomic","fee_atomic","fee_usdc","merchant_net_after_fee_atomic","merchant_net_after_fee_usdc","fee_collection","facilitator_and_sponsored_gas_surcharge_atomic"],"properties":{"fee_bps":{"type":"integer","const":50},"minimum_fee_atomic":{"type":"string","const":"1000"},"maximum_fee_atomic":{"type":"string","const":"100000"},"fee_atomic":{"type":"string"},"fee_usdc":{"type":"string"},"merchant_net_after_fee_atomic":{"type":"string"},"merchant_net_after_fee_usdc":{"type":"string"},"fee_collection":{"type":"object"},"facilitator_and_sponsored_gas_surcharge_atomic":{"type":"string","const":"0"}}},"resource_url":{"type":"string","format":"uri"},"payer_wallet":{"type":["string","null"]},"transaction_hash":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"}}},"Error":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"errors":{"type":"object"}}},"OAuthError":{"type":"object","required":["error","error_description"],"properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}},"responses":{"Capabilities":{"description":"Public service capabilities","content":{"application\/json":{"schema":{"type":"object"}}}},"Connection":{"description":"Merchant connection","content":{"application\/json":{"schema":{"type":"object"}}}},"Networks":{"description":"Ready merchant networks","content":{"application\/json":{"schema":{"type":"object"}}}},"Onboarding":{"description":"Agent-assisted merchant onboarding state","content":{"application\/json":{"schema":{"type":"object"}}}},"PaymentIntent":{"description":"Payment intent","content":{"application\/json":{"schema":{"type":"object","properties":{"payment_intent":{"$ref":"#\/components\/schemas\/PaymentIntent"}}}}}},"X402Payment":{"description":"x402 payment request","content":{"application\/json":{"schema":{"type":"object","properties":{"payment":{"$ref":"#\/components\/schemas\/X402Payment"}}}}}},"Error":{"description":"Error response","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"OAuthError":{"description":"OAuth error response","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/OAuthError"}}}}}}}