# AgiPay

AI membership storefront with an order-based x402 v2 checkout on BSC.

Current payment availability: enabled.

## Interfaces
- [Agent overview](https://agipay402.com/agent-payments)
- [JavaScript client example](https://agipay402.com/agent-client.mjs) (ethers v6; caller supplies an authorized signer, spending limit and expected receiver)
- [API specification](https://agipay402.com/openapi.json)
- [Availability](https://agipay402.com/api/health)
- [Catalog](https://agipay402.com/api/catalog)

## Identity
POST /api/auth/challenge with {"wallet":"0x..."}. Sign the exact returned message with personal_sign using that wallet, then POST /api/auth/session with {"id":"challenge id","signature":"0x..."}. The response contains a 15-minute session token. Use Authorization: Bearer <session token> on all order endpoints. Login does not authorize spending. After expiry or server restart, sign in again with the same wallet; historical orders remain available. GET /api/auth/me checks the session; POST /api/auth/logout revokes it. The payer must be the logged-in wallet. Separate agent wallets are separate identities; delegated payment is not supported in this version.

## Purchase workflow
1. Read /api/health; require paymentReady=true. Payment is followed by order processing. Delivery may take time; check the order page for progress.
2. Read /api/catalog, then GET /api/products/{productId}/checkout-options to select an available SKU.
3. POST /api/orders with JSON {"productId":1,"skuId":1}. These IDs are examples; use live IDs. Include the wallet session and an Idempotency-Key header containing a stable 16–100 character alphanumeric, dash or underscore request ID. Reuse that key and the same body when retrying; save the returned order id. Creating a quote does not charge money.
4. POST /api/orders/{id}/pay with Authorization: Bearer <session token>. HTTP 402 and PAYMENT-REQUIRED provide the exact BSC USDT price, recipient, and resource.
5. Use BSC chain ID 56, USDT 0x55d398326f99059fF775485246999027B3197955 (18 decimals). Approve Permit2 0x000000000022D473030F116dDEE9F6B43aC78BA3 for the exact amount if needed (requires BNB gas). Sign PermitWitnessTransferFrom under the Permit2 domain with spender 0x402085c248EeA27D92E8b30b2C58ed07f9E20001; witness={to:payTo,validAfter:0}. Set permitted={token:asset,amount}, from=payer, nonce=a fresh SDK-generated uint256 (the suggested extensions.agipay-order.nonce is optional) and deadline <= floor(extensions.agipay-order.expiresAt/1000). The server persistently binds the first valid signed nonce to this order and rejects reuse on other orders. Use the returned maxTimeoutSeconds for your signature deadline. Only the plain exact Permit2 settle path is supported, without gas-sponsoring extensions. Never reuse payment authorizations from another order.
6. Resubmit with PAYMENT-SIGNATURE containing base64-encoded x402 v2 JSON (x402Version, resource, accepted, payload.signature, payload.permit2Authorization) and a valid session for the same wallet. Payment may be settled on-chain at this step.
7. GET /api/orders lists the authenticated wallet's orders. Poll GET /api/orders/{id} with the session token, at most once every 15 seconds. A payment response is not delivery. Wait for state=delivered and read delivery.
8. If state is confirming_payment, awaiting_procurement, payment_review, or needs_attention, do not create a replacement charge. Preserve the order ID for reconciliation.

Only auto-fulfillment SKUs are enabled. Final USDT quotes convert the displayed retail price using a dated CNY/USD reference and treat 1 USDT as 1 USD. Review the exact amount and recipient before authorizing spending.
Session tokens, legacy recovery credentials and delivered content are private. Do not put tokens in URLs or public discovery catalogs.

## Base USDC Agent channel
See /base-agent.txt and /api/agent/health. Only use this channel when paymentReady=true. The public purchase endpoint authenticates spending using the payer signature; private delivery still requires wallet login.

## Discovery status
This document and OpenAPI describe the service. They do not imply registration in an external x402 Bazaar, or guarantee that every AI automatically discovers it.

## Virtual cards
Virtual card issuing and recharge using x402: https://agipay402.com/cards-agent.txt
Availability: https://agipay402.com/api/cards/health
Specification: https://agipay402.com/cards-openapi.json