From 281e0accbf324f2aff4ede9eec1008a01da6cfca Mon Sep 17 00:00:00 2001 From: akbarsaputrait Date: Sun, 21 Sep 2025 22:56:11 +0700 Subject: [PATCH 1/3] feat: add Intent API Docs --- .DS_Store | Bin 0 -> 6148 bytes SUMMARY.md | 6 +- intent-pay/.DS_Store | Bin 0 -> 6148 bytes intent-pay/API/README.md | 73 +++++++ intent-pay/API/endpoints.md | 148 +++++++++++++ intent-pay/API/payment-bridging.md | 333 +++++++++++++++++++++++++++++ intent-pay/API/types.md | 156 ++++++++++++++ intent-pay/troubleshooting.md | 2 +- 8 files changed, 716 insertions(+), 2 deletions(-) create mode 100644 .DS_Store create mode 100644 intent-pay/.DS_Store create mode 100644 intent-pay/API/README.md create mode 100644 intent-pay/API/endpoints.md create mode 100644 intent-pay/API/payment-bridging.md create mode 100644 intent-pay/API/types.md diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..5008ddfcf53c02e82d7eee2e57c38e5672ef89f6 GIT binary patch literal 6148 zcmeH~Jr2S!425mzP>H1@V-^m;4Wg<&0T*E43hX&L&p$$qDprKhvt+--jT7}7np#A3 zem<@ulZcFPQ@L2!n>{z**++&mCkOWA81W14cNZlEfg7;MkzE(HCqgga^y>{tEnwC%0;vJ&^%eQ zLs35+`xjp>T0H1@V-^m;4Wg<&0T*E43hX&L&p$$qDprKhvt+--jT7}7np#A3 zem<@ulZcFPQ@L2!n>{z**++&mCkOWA81W14cNZlEfg7;MkzE(HCqgga^y>{tEnwC%0;vJ&^%eQ zLs35+`xjp>T0 + +## Pay In Options + +Users can pay from different chains while paying out to their preferred destination: + +### Pay In from Polygon USDC + +```javascript +const paymentData = { + // ... destination stays the same + preferredChain: "137", // Polygon chain ID + preferredToken: "USDC", + preferredTokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // Polygon USDC +}; +``` + +### Pay In from Stellar USDC (Memo Required) + +When users pay in from Stellar, a memo is **required** for the payment transaction. + +```javascript +const paymentData = { + // ... destination stays the same + preferredChain: "1500", // Stellar chain ID + preferredToken: "USDC", + // No preferredTokenAddress needed for Stellar +}; + +// After creating the payment, check for memo requirement +const payment = await createPayment(paymentData); + +if (payment.metadata.memo) { + console.log("MEMO REQUIRED for Stellar payment:", payment.metadata.memo); + // User MUST include this memo when sending Stellar USDC +} +``` + +### Pay In from Solana USDC (Memo Required) + +When users pay in from Solana, a memo is **required** for the payment transaction. + +```javascript +const paymentData = { + // ... destination stays the same + preferredChain: "900", // Solana chain ID + preferredToken: "USDC", + preferredTokenAddress: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // Solana USDC +}; + +// After creating the payment, check for memo requirement +const payment = await createPayment(paymentData); + +if (payment.metadata.memo) { + console.log("MEMO REQUIRED for Solana payment:", payment.metadata.memo); + // User MUST include this memo when sending Solana USDC +} +``` + +### Pay In from BSC USDT + +```javascript +const paymentData = { + // ... destination stays the same + preferredChain: "56", // BSC chain ID + preferredToken: "USDT", + preferredTokenAddress: "0x55d398326f99059fF775485246999027B3197955", // BSC USDT +}; +``` + +## Complete Example: Cross-Chain Payment + +```javascript +async function createCrossChainPayment() { + // User wants to pay out to Stellar USDC, but pay in from Polygon + const paymentRequest = { + appId: "my-app", + display: { + intent: "Cross-chain payment to Stellar", + paymentValue: "250.00", + currency: "USD", + }, + // Pay OUT to Stellar + destination: { + destinationAddress: + "GCKFBEIYTKP7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5", + chainId: "stellar-mainnet", + amountUnits: "250000000", // $250 USDC + tokenSymbol: "USDC", + tokenAddress: + "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN", + }, + // Pay IN from Polygon + preferredChain: "137", + preferredToken: "USDC", + preferredTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", + externalId: "payment_123", + metadata: { + userId: "user_456", + description: "Cross-chain USDC transfer", + }, + }; + + try { + const response = await fetch("https://intentapi.rozo.ai/payment-api", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_API_KEY", + }, + body: JSON.stringify(paymentRequest), + }); + + const payment = await response.json(); + + // IMPORTANT: Always use receivingAddress from response + const finalDestination = payment.metadata.receivingAddress; + const checkoutUrl = payment.url; + + console.log( + "Original destination:", + paymentRequest.destination.destinationAddress + ); + console.log("Final receiving address:", finalDestination); + console.log("Payment ID:", payment.id); + console.log("Checkout URL:", checkoutUrl); + + return { + paymentId: payment.id, + finalDestination, + checkoutUrl, + status: payment.status, + payInChain: payment.metadata.payinchainid, + payInToken: payment.metadata.payintokenaddress, + memo: payment.metadata.memo, // Required for Stellar/Solana + memoRequired: payment.metadata.memo !== null, + }; + } catch (error) { + console.error("Payment creation failed:", error); + throw error; + } +} +``` + +## Chain and Token Reference + +### Supported Chains + +| Chain | Chain ID | Description | +| ------- | ---------------- | ------------------- | +| Base | `8453` | Base mainnet | +| Polygon | `137` | Polygon mainnet | +| BSC | `56` | Binance Smart Chain | +| Stellar | `1500` | Stellar network | +| Solana | `solana-mainnet` | Solana network | + +### Token Addresses + +#### USDC Addresses + +- **Base**: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` +- **Polygon**: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` +- **Stellar**: `USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN` +- **Solana**: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` + +#### USDT Addresses + +- **BSC**: `0x55d398326f99059fF775485246999027B3197955` + +## Error Handling + +```javascript +async function createPaymentWithErrorHandling(paymentData) { + try { + const payment = await createRozoPayment(paymentData); + + if (!payment.data?.id) { + throw new Error(payment.error?.message || "Payment creation failed"); + } + + // Extract receiving address if provided + const receivingAddress = payment.data.metadata?.receivingAddress; + + return { + success: true, + paymentId: payment.data.id, + receivingAddress: + receivingAddress || paymentData.destination.destinationAddress, + originalDestination: paymentData.destination.destinationAddress, + }; + } catch (error) { + console.error("Payment creation error:", error); + return { + success: false, + error: error.message, + }; + } +} +``` + +## Best Practices + +1. **Always check for receivingAddress** in the API response +2. **Check for memo requirements** - required for Stellar and Solana payments +3. **Store both original and final destinations** for tracking +4. **Use external IDs** to correlate payments with your system +5. **Include comprehensive metadata** for better tracking +6. **Handle cross-chain delays** - payments may take time to process +7. **Validate chain IDs and token addresses** before sending +8. **Monitor payment status** using the GET endpoint + +## Payment Status Flow + +1. **payment_unpaid** - Payment created, awaiting user payment +2. **payment_progress** - Cross-chain bridge in progress +3. **payment_completed** - Funds delivered to final destination +4. **payment_expired** - Payment expired diff --git a/intent-pay/API/types.md b/intent-pay/API/types.md new file mode 100644 index 0000000..cbd661c --- /dev/null +++ b/intent-pay/API/types.md @@ -0,0 +1,156 @@ +# Data Types & Schemas + +## Core Interfaces + +### PaymentDisplay + +Display information for user interfaces. + +```typescript +interface PaymentDisplay { + intent: string; // Payment description/purpose + paymentValue: string; // Human-readable amount (e.g., "29.99") + currency: string; // Currency code (USD, EUR, etc.) +} +``` + +### PaymentDestination + +Where the payment should be sent. + +```typescript +interface PaymentDestination { + destinationAddress?: string; // Recipient wallet address + chainId: string; // Blockchain network ID + amountUnits: string; // Amount in smallest token units + tokenSymbol: string; // Token symbol (USDC, ETH, etc.) + tokenAddress?: string; // Token contract address + txHash?: string | null; // Transaction hash (set after payment) +} +``` + +### PaymentSource + +Payment source information. + +```typescript +interface PaymentSource { + sourceAddress?: string; // Sender wallet address + [key: string]: unknown; // Additional metadata +} +``` + +### PaymentRequestData + +Data required to create a payment. + +```typescript +interface PaymentRequestData { + appId: string; // Your application ID + display: PaymentDisplay; // Display information + destination: PaymentDestination; // Payment destination + externalId?: string; // Your internal reference ID + metadata?: Record; // Additional metadata + preferredChain?: string; // Preferred blockchain + preferredToken?: string; // Preferred token symbol + preferredTokenAddress?: string; // Preferred token address + [key: string]: unknown; // Extensible for future fields +} +``` + +### PaymentResponseData + +Complete payment information from API. + +```typescript +interface PaymentResponseData { + id: string; // Unique payment ID + status: string; // Payment status (e.g., "payment_unpaid") + createdAt: string; // ISO timestamp + display: { + intent: string; // Payment intent + currency: string; // Currency (e.g., "USDC") + }; + source: PaymentSource | null; // Source information (null initially) + destination: { + destinationAddress: string; // Recipient address + txHash: string | null; // Transaction hash (null initially) + chainId: string; // Chain ID (e.g., "1500" for Stellar) + amountUnits: string; // Amount in token units + tokenSymbol: string; // Token symbol + tokenAddress: string; // Token contract/asset address + }; + metadata: { + receivingAddress?: string; // IMPORTANT: Final receiving address + payinchainid?: string; // Pay-in chain ID + payintokenaddress?: string; // Pay-in token address + memo?: string | null; // REQUIRED memo for Stellar and Solana payments + webhookUrl?: string; // Webhook URL for notifications + [key: string]: unknown; // Additional metadata + }; + url: string; // Checkout URL for payment +} +``` + +### ApiResponse + +Standard API response wrapper. + +```typescript +interface ApiResponse { + data: T | null; // Response data + error: Error | null; // Error information + status: number | null; // HTTP status code +} +``` + +### RequestState + +Hook state for React components. + +```typescript +interface RequestState { + data: T | null; // Response data + error: Error | null; // Error information + status: number | null; // HTTP status + isLoading: boolean; // Loading state + isError: boolean; // Error state + isSuccess: boolean; // Success state +} +``` + +## Payment Status Values + +| Status | Description | +| ---------------- | ------------------------------ | +| `payment_unpaid` | Payment created, awaiting user | +| `processing` | Payment being processed | +| `completed` | Payment successful | +| `failed` | Payment failed | +| `cancelled` | Payment cancelled | +| `expired` | Payment expired | + +## Chain IDs + +Common blockchain network identifiers: + +| Chain | ID | Name | +| ------- | ------ | ------------------- | +| Base | `8453` | Mainnet | +| Polygon | `137` | Polygon | +| BSC | `56` | Binance Smart Chain | +| Stellar | `1500` | Stellar Mainnet | +| Solana | `900` | Solana Mainnet | + +## Token Addresses + +### USDC Addresses + +- Base: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` +- Polygon: `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` +- Stellar: `USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN` +- Solana: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` + +### USDT Address + +- BSC: `0x55d398326f99059fF775485246999027B3197955` diff --git a/intent-pay/troubleshooting.md b/intent-pay/troubleshooting.md index 13826d9..ac6454a 100644 --- a/intent-pay/troubleshooting.md +++ b/intent-pay/troubleshooting.md @@ -111,7 +111,7 @@ If you're still experiencing issues: - ๐Ÿ› **GitHub Issues**: [GitHub Issues](https://github.com/rozoai/intent-pay/issues) 3. **Direct Support:** - - ๐Ÿ“ง **Email**: support@rozo.ai + - ๐Ÿ“ง **Email**: When reporting issues, please include: From df7c7cb2ee0c0b76ca50aa4054a1d06d3bc5211d Mon Sep 17 00:00:00 2001 From: akbarsaputrait Date: Sun, 21 Sep 2025 23:10:22 +0700 Subject: [PATCH 2/3] feat: improve intent AI promp --- intent-pay/ai-prompts.md | 26 ++++++++++++++++++++++++-- intent-pay/quick-start.md | 2 +- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/intent-pay/ai-prompts.md b/intent-pay/ai-prompts.md index 686a939..63e8621 100644 --- a/intent-pay/ai-prompts.md +++ b/intent-pay/ai-prompts.md @@ -4,8 +4,30 @@ Use this prompt with any AI service to generate a complete RozoAI Intent Pay implementation: -``` -Create a React component with RozoAI Intent Pay SDK for crypto payments. Use demo app ID "rozoDemo" for testing, accept Base USDC payments (chain ID 8453), and include all required providers (WagmiProvider, QueryClientProvider, RozoPayProvider) in proper nesting order. IMPORTANT: Use getDefaultConfig from @rozoai/intent-pay (NOT createConfig from wagmi) to create the wagmiConfig. Add payment event handlers (onPaymentStarted, onPaymentCompleted, onPaymentBounced) with console logging and user-friendly alerts. Use TypeScript with proper types, include form validation if creating input fields, and ensure mobile-responsive design with TailwindCSS. Import baseUSDC from @rozoai/intent-common and wrap addresses with getAddress() from viem. Refer to this Guide Docs: https://docs.rozo.ai/intent-pay/quick-start.md +```text +Create a React component with RozoAI Intent Pay SDK for crypto payments. +Use demo app ID "rozoDemo" for testing, accept Base USDC payments +(chain ID 8453), and include all required providers +(WagmiProvider, QueryClientProvider, RozoPayProvider) +in proper nesting order. + +IMPORTANT: +- Use getDefaultConfig from @rozoai/intent-pay + (NOT createConfig from wagmi) to create the wagmiConfig. +- Ensure the code imports packages from the latest SDK release, not from + deprecated or older versions. Use @rozoai/intent-pay@latest and @rozoai/intent-common@latest + +Add payment event handlers (onPaymentStarted, onPaymentCompleted, +onPaymentBounced) with console logging and user-friendly alerts. + +Use TypeScript with proper types, include form validation if creating +input fields, and ensure mobile-responsive design with TailwindCSS. + +Import baseUSDC from @rozoai/intent-common and wrap addresses +with getAddress() from viem. + +Refer to this Guide Docs: +https://docs.rozo.ai/intent-pay/quick-start.md ``` ## ๐Ÿš€ One-Click Generation diff --git a/intent-pay/quick-start.md b/intent-pay/quick-start.md index b46b263..02d677d 100644 --- a/intent-pay/quick-start.md +++ b/intent-pay/quick-start.md @@ -5,7 +5,7 @@ Get up and running with RozoAI Intent Pay SDK in 5 minutes. ## ๐Ÿš€ Installation ```bash -npm install @rozoai/intent-pay @rozoai/intent-common @tanstack/react-query wagmi viem +npm install @rozoai/intent-pay@latest @rozoai/intent-common@latest @tanstack/react-query wagmi viem ``` ## ๐Ÿ“ Basic Setup From 50e01608a725d6af5a480b4ddf99f217220ed16d Mon Sep 17 00:00:00 2001 From: akbarsaputrait Date: Mon, 22 Sep 2025 15:12:02 +0700 Subject: [PATCH 3/3] fix: pr review --- .DS_Store | Bin 6148 -> 0 bytes intent-pay/.DS_Store | Bin 6148 -> 0 bytes intent-pay/API/README.md | 2 +- intent-pay/API/payment-bridging.md | 4 ++-- 4 files changed, 3 insertions(+), 3 deletions(-) delete mode 100644 .DS_Store delete mode 100644 intent-pay/.DS_Store diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index 5008ddfcf53c02e82d7eee2e57c38e5672ef89f6..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6148 zcmeH~Jr2S!425mzP>H1@V-^m;4Wg<&0T*E43hX&L&p$$qDprKhvt+--jT7}7np#A3 zem<@ulZcFPQ@L2!n>{z**++&mCkOWA81W14cNZlEfg7;MkzE(HCqgga^y>{tEnwC%0;vJ&^%eQ zLs35+`xjp>T0H1@V-^m;4Wg<&0T*E43hX&L&p$$qDprKhvt+--jT7}7np#A3 zem<@ulZcFPQ@L2!n>{z**++&mCkOWA81W14cNZlEfg7;MkzE(HCqgga^y>{tEnwC%0;vJ&^%eQ zLs35+`xjp>T0