diff --git a/abstract-global-wallet/fiat-on-ramp/config.mdx b/abstract-global-wallet/fiat-on-ramp/config.mdx new file mode 100644 index 0000000..3b5dab9 --- /dev/null +++ b/abstract-global-wallet/fiat-on-ramp/config.mdx @@ -0,0 +1,187 @@ +--- +title: "/config" +api: "GET https://onramp.staging-portal.abs.xyz/config" +description: "Return a list of countries, purchase limits, and service providers available for onramp." +--- + +## Response + + + Array of supported countries with their regions and default currencies + + + The ISO 3166 2-digit country code + + + The display name for the Country + + + The URL to the Country's flag image + + + The set of supported regions within the Country. If null, then all regions within the Country are supported + + + The alphanumeric code (ISO 3166-2) for the Region + + + The display name for the Region + + + + + The currency code for the default currency of this country + + + + + + Array of purchase limits by currency + + + The currency code + + + The default purchase amount + + + The minimum purchase amount + + + The maximum purchase amount + + + + + + Array of available service providers + + + Service provider identifier + + + Display name of the service provider + + + Current status of the provider + + + Array of service categories + + + Status of each category + + + Provider's website URL + + + Provider's customer support URL + + + Provider logos for different themes + + + Dark theme logo URL + + + Light theme logo URL + + + Dark theme short logo URL + + + Light theme short logo URL + + + + + + + + +```bash cURL +curl -X GET "https://onramp.staging-portal.abs.xyz/config" +``` + +```javascript JavaScript +const response = await fetch('https://onramp.staging-portal.abs.xyz/config'); +const config = await response.json(); +``` + + + + + +```json Response +{ + "countries": [ + { + "countryCode": "CA", + "name": "Canada", + "flagImageUrl": "https://images-country.meld.io/CA/flag.svg", + "regions": [ + { + "regionCode": "CA-AB", + "name": "Alberta" + }, + { + "regionCode": "CA-BC", + "name": "British Columbia" + } + ], + "defaultFiatCurrency": "CAD" + }, + { + "countryCode": "US", + "name": "United States", + "flagImageUrl": "https://images-country.meld.io/US/flag.svg", + "regions": [ + { + "regionCode": "US-CA", + "name": "California" + }, + { + "regionCode": "US-NY", + "name": "New York" + } + ], + "defaultFiatCurrency": "USD" + } + ], + "limits": [ + { + "currencyCode": "CAD", + "defaultAmount": 400, + "minimumAmount": 15.64, + "maximumAmount": 23303.6 + }, + { + "currencyCode": "USD", + "defaultAmount": 300, + "minimumAmount": 9.18, + "maximumAmount": 17094.78 + } + ], + "serviceProviders": [ + { + "serviceProvider": "TRANSAK", + "name": "Transak", + "status": "LIVE", + "categories": ["CRYPTO_ONRAMP"], + "categoryStatuses": { + "CRYPTO_ONRAMP": "LIVE" + }, + "websiteUrl": "https://transak.com", + "customerSupportUrl": "", + "logos": { + "dark": "https://images-serviceprovider.meld.io/TRANSAK/logo_dark.png", + "light": "https://images-serviceprovider.meld.io/TRANSAK/logo_light.png", + "darkShort": "https://images-serviceprovider.meld.io/TRANSAK/short_logo_dark.png", + "lightShort": "https://images-serviceprovider.meld.io/TRANSAK/short_logo_light.png" + } + } + ] +} +``` + + \ No newline at end of file diff --git a/abstract-global-wallet/fiat-on-ramp/currencies.mdx b/abstract-global-wallet/fiat-on-ramp/currencies.mdx new file mode 100644 index 0000000..eb18c61 --- /dev/null +++ b/abstract-global-wallet/fiat-on-ramp/currencies.mdx @@ -0,0 +1,114 @@ +--- +title: "/currencies" +api: "GET https://onramp.staging-portal.abs.xyz/currencies" +description: "Return a list of FIAT and crypto currencies for the provided country." +--- + +## Query Parameters + + + The ISO 3166 2-digit country code + + +## Response + + + Array of supported fiat currencies + + + The code for this Fiat Currency + + + The display name for this Fiat Currency + + + The URL to this Fiat Currency's symbol image + + + The ASCII symbol for this Fiat Currency + + + + + + Array of supported crypto currencies + + + The code for the Crypto Currency + + + The display name for the Crypto Currency + + + The code for the chain the Crypto Currency is on + + + The display name for the chain the Crypto Currency is on + + + The id for the chain the Crypto Currency is on + + + The contract address of the Crypto Currency + + + The URL to the Crypto Currency's symbol image + + + + + + +```bash cURL +curl -X GET "https://onramp.staging-portal.abs.xyz/currencies?country=US" +``` + +```javascript JavaScript +const response = await fetch('https://onramp.staging-portal.abs.xyz/currencies?country=US'); +const currencies = await response.json(); +``` + + + + + +```json Response +{ + "fiat": [ + { + "currencyCode": "USD", + "name": "US Dollar", + "symbolImageUrl": "https://images-currency.meld.io/fiat/USD/symbol.png", + "symbol": "$" + }, + { + "currencyCode": "EUR", + "name": "Euro", + "symbolImageUrl": "https://images-currency.meld.io/fiat/EUR/symbol.png", + "symbol": "€" + } + ], + "crypto": [ + { + "currencyCode": "ETH_BASE", + "name": "Ethereum", + "chainCode": "BASE", + "chainName": "Base", + "chainId": null, + "contractAddress": null, + "symbolImageUrl": "https://images-currency.meld.io/crypto/ETH_BASE/symbol.png" + }, + { + "currencyCode": "USDC_BASE", + "name": "USD Coin", + "chainCode": "BASE", + "chainName": "Base", + "chainId": null, + "contractAddress": null, + "symbolImageUrl": "https://images-currency.meld.io/crypto/USDC_BASE/symbol.png" + } + ] +} +``` + + \ No newline at end of file diff --git a/abstract-global-wallet/fiat-on-ramp/overview.mdx b/abstract-global-wallet/fiat-on-ramp/overview.mdx new file mode 100644 index 0000000..fbe2ccc --- /dev/null +++ b/abstract-global-wallet/fiat-on-ramp/overview.mdx @@ -0,0 +1,88 @@ +--- +title: "FIAT On-ramp" +sidebarTitle: "Overview" +description: "Learn how to allow users to fund their Abstract Global Wallet with FIAT currencies." +--- + +To provide a consumer-friendly onboarding experience to non-crypto-native users, +Abstract supports a FIAT on-ramp powered by [Meld](https://www.meld.io/). + +This enables users in over 200 countries to fund their Abstract Global Wallet using their local currency via a credit card, Apple Pay, or Google Pay. + + + + View a demo application that uses AGW and FIAT on-ramp to test the flow. + + + Use our example repo to quickly get started with AGW and FIAT on-ramp. + + + +## How it works + +The FIAT on-ramp works by presenting users with a **widget** that prompts the user for their payment details to fulfill a **quote**. The quote determines the amount, address, currency, and other details of the transaction. + +This flow can be broken down into three steps: + + + + To generate a **quote**, information about the user and their desired on-ramp transaction is required, including the user’s country, wallet address, desired amount, etc. (see [/quote](/abstract-global-wallet/fiat-on-ramp/quote) for more details). + + Present users with a form to collect the required information, making use of the below endpoints to localize and validate the user’s input: + + - [/config](/abstract-global-wallet/fiat-on-ramp/config) to get the user’s country and local currency information. + - [/currencies](/abstract-global-wallet/fiat-on-ramp/currencies) to get the available currencies for the user’s country. + - [/payment-methods](/abstract-global-wallet/fiat-on-ramp/payment-methods) to get the available payment methods for the user’s country. + + + + After collecting the required information from the user, call the [/quote endpoint](/abstract-global-wallet/fiat-on-ramp/quote) to get an array of quotes from providers that can fulfill the given request. + + Choose *(or allow the user to choose)* the best quote for your application’s needs. + + + + Provide your selected quote to the [/widget endpoint](/abstract-global-wallet/fiat-on-ramp/widget) to generate a widget URL that can be either opened directly or embedded in your application using an iframe. + + The widget URL presents the user with a form to enter their payment details and complete the transaction. Use the [/transactions endpoint](/abstract-global-wallet/fiat-on-ramp/transactions) to track the status of their order using the session ID returned from the widget. + + + + +Under the hood, funds are first loaded to a temporary deposit address on the [Base network](https://www.base.org/) before being bridged to the desired destination address on Abstract. + + +## API Overview + +Abstract provides a simplified API to help you integrate the FIAT on-ramp into your application. + +### Base URLs + +It is recommended to use the staging environment for testing and development. + +| Staging | Production | +|---------|------------| +| `https://onramp.staging-portal.abs.xyz/` | `https://onramp.portal.abs.xyz/` | + +### Endpoints + +Below is a summary of the available endpoints. + +| Endpoint | Description | +|----------|-------------| +| [/config](/abstract-global-wallet/fiat-on-ramp/config) | Return a list of countries, purchase limits, and service providers available for on-ramp. | +| [/currencies](/abstract-global-wallet/fiat-on-ramp/currencies) | Return a list of FIAT and crypto currencies for the provided country. | +| [/payment-methods](/abstract-global-wallet/fiat-on-ramp/payment-methods) | Return a list of payment methods for the provided country. | +| [/quote](/abstract-global-wallet/fiat-on-ramp/quote) | Generate quotes for purchasing cryptocurrency with FIAT currency. | +| [/transactions](/abstract-global-wallet/fiat-on-ramp/transactions) | Get on-ramp transaction status and history. | +| [/widget](/abstract-global-wallet/fiat-on-ramp/widget) | Create a session for buying crypto with FIAT currency. | + + diff --git a/abstract-global-wallet/fiat-on-ramp/payment-methods.mdx b/abstract-global-wallet/fiat-on-ramp/payment-methods.mdx new file mode 100644 index 0000000..362e1d6 --- /dev/null +++ b/abstract-global-wallet/fiat-on-ramp/payment-methods.mdx @@ -0,0 +1,90 @@ +--- +title: "/payment-methods" +api: "GET https://onramp.staging-portal.abs.xyz/payment-methods" +description: "Return a list of payment methods for the provided country." +--- + +## Query Parameters + + + The ISO 3166 2-digit country code + + +## Response + + + Array of supported payment methods + + + The identifier for the Payment Method + + + The display name for the Payment Method + + + The type of Payment Method (`ACH`, `BANK_TRANSFER`, `CARD`, `LOCAL`, `MOBILE_WALLET`, `SEPA`) + + + Payment method logos for different themes + + + The light logo URL for the Payment Method + + + The dark logo URL for the Payment Method + + + + + + + + +```bash cURL +curl -X GET "https://onramp.staging-portal.abs.xyz/payment-methods?country=US" +``` + +```javascript JavaScript +const response = await fetch('https://onramp.staging-portal.abs.xyz/payment-methods?country=US'); +const paymentMethods = await response.json(); +``` + + + + + +```json Response +{ + "paymentMethods": [ + { + "paymentMethod": "CREDIT_DEBIT_CARD", + "name": "Credit & Debit Card", + "paymentType": "CARD", + "logos": { + "dark": "https://images-paymentMethod.meld.io/CREDIT_DEBIT_CARD/logo_dark.png", + "light": "https://images-paymentMethod.meld.io/CREDIT_DEBIT_CARD/logo_light.png" + } + }, + { + "paymentMethod": "APPLE_PAY", + "name": "Apple Pay", + "paymentType": "MOBILE_WALLET", + "logos": { + "dark": "https://images-paymentMethod.meld.io/APPLE_PAY/logo_dark.png", + "light": "https://images-paymentMethod.meld.io/APPLE_PAY/logo_light.png" + } + }, + { + "paymentMethod": "GOOGLE_PAY", + "name": "Google Pay", + "paymentType": "MOBILE_WALLET", + "logos": { + "dark": "https://images-paymentMethod.meld.io/GOOGLE_PAY/logo_dark.png", + "light": "https://images-paymentMethod.meld.io/GOOGLE_PAY/logo_light.png" + } + } + ] +} +``` + + \ No newline at end of file diff --git a/abstract-global-wallet/fiat-on-ramp/quote.mdx b/abstract-global-wallet/fiat-on-ramp/quote.mdx new file mode 100644 index 0000000..da2db73 --- /dev/null +++ b/abstract-global-wallet/fiat-on-ramp/quote.mdx @@ -0,0 +1,162 @@ +--- +title: "/quote" +api: "GET https://onramp.staging-portal.abs.xyz/quote" +description: "Generate quotes for purchasing cryptocurrency with FIAT currency." +--- + +## Query Parameters + + + The ISO 3166 2-digit country code + + + + The code for the Crypto Currency (e.g., "ETH_BASE", "USDC_BASE") + + + + The code for the Fiat Currency (e.g., "USD", "CAD") + + + + The amount (in source currency) to buy + + + + The identifier for the Payment Method + + + + The wallet address for the user making this request (does not have to be AGW) + + +## Response + + + Array of available quotes from different providers + + + Always "CRYPTO_PURCHASE" + + + Amount requested + fees + + + The fiat amount being used to buy crypto, excluding fees + + + The fiat amount exchanged when buying crypto, excluding fees + + + The fiat amount exchanged when selling crypto, excluding fees + + + Three-letter ISO currency code. Must be a supported currency + + + Two-letter country code + + + Total fees for the transaction + + + The network fee applied to a crypto transaction + + + The fee amount charged by the service provider to process the purchase + + + Destination currency amount to be received for this quote + + + Code of currency being quoted + + + The exchange rate at the time the request is sent + + + Payment Method Type used for this quote + + + A numerical score representing the expectation a Customer will convert + + + Service Provider used on this quote + + + The name of the institution or broker used for this quote, if present + + + Indicates if the quote amount is below the provider's low KYC threshold + + + The fee amount charged by the partner to process the purchase + + + The wallet address for the user making this request + + + The deposit address on Base that will receive the crypto and bridge it to Abstract + + + The fee amount charged by Relay for the deposit address + + + + + + +```bash cURL +curl -X GET "https://onramp.staging-portal.abs.xyz/quote?country=US&destinationCurrency=USDC_BASE&sourceCurrency=USD&amount=100&paymentMethod=CREDIT_DEBIT_CARD&walletAddress=0xfc61f1b7701f6765ff548b3bca403cdaa723d260" +``` + +```javascript JavaScript +const params = new URLSearchParams({ + country: 'US', + destinationCurrency: 'USDC_BASE', + sourceCurrency: 'USD', + amount: '100', + paymentMethod: 'CREDIT_DEBIT_CARD', + walletAddress: '0xfc61f1b7701f6765ff548b3bca403cdaa723d260' +}); + +const response = await fetch(`https://onramp.staging-portal.abs.xyz/quote?${params}`); +const quote = await response.json(); +``` + + + + + +```json Response +{ + "quotes": [ + { + "transactionType": "CRYPTO_PURCHASE", + "sourceAmount": 100, + "sourceAmountWithoutFees": 93.3317, + "fiatAmountWithoutFees": 93.3317, + "destinationAmountWithoutFees": null, + "sourceCurrencyCode": "USD", + "countryCode": "US", + "totalFee": 6.68, + "networkFee": null, + "transactionFee": 5.5, + "destinationAmount": 68.017348, + "destinationCurrencyCode": "USDC_BASE", + "exchangeRate": 1.468, + "paymentMethodType": "CREDIT_DEBIT_CARD", + "customerScore": 20, + "serviceProvider": "TRANSAK", + "institutionName": null, + "lowKyc": null, + "partnerFee": 1, + "walletAddress": "0xfc61f1b7701f6765ff548b3bca403cdaa723d260", + "toAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", + "relayFee": 0.18 + } + ] +} +``` + + \ No newline at end of file diff --git a/abstract-global-wallet/fiat-on-ramp/transactions.mdx b/abstract-global-wallet/fiat-on-ramp/transactions.mdx new file mode 100644 index 0000000..05efb28 --- /dev/null +++ b/abstract-global-wallet/fiat-on-ramp/transactions.mdx @@ -0,0 +1,144 @@ +--- +title: "/transactions" +api: "GET https://onramp.staging-portal.abs.xyz/transactions" +description: "Get on-ramp transaction status and history." +--- + +Retrieves transaction status for onramp purchases. + +- `/transactions/status` for a single transaction +- `/transactions` for multiple transactions + + +## Get Single Transaction Status + +**GET** `/transactions/status` + +Gets the status of a single transaction using the session ID. + + + The session ID from the widget redirect URL query parameters + + +## Get Multiple Transactions + +**GET** `/transactions` + +Gets all transactions for a user or app. Provide either `walletAddress` or `referrer` (or both) to filter transactions. + + + The wallet address to get transactions for + + + + The name of the app to get transactions for + + +## Response + +The response format varies depending on the endpoint used. Both endpoints return transaction objects with status information. + + + Current status of the transaction (e.g., "PENDING", "COMPLETED", "FAILED") + + + + Transaction amount in source currency + + + + Source currency code + + + + Amount received in destination currency + + + + Destination currency code + + + + Blockchain transaction hash (when available) + + + + Transaction creation timestamp + + + + Last update timestamp + + + + +```bash Single Transaction Status +curl -X GET "https://onramp.staging-portal.abs.xyz/transactions/status?sessionId=WePzm7gRdUgis7VHQjMYYL" +``` + +```bash Multiple Transactions by Wallet +curl -X GET "https://onramp.staging-portal.abs.xyz/transactions?walletAddress=0xfc61f1b7701f6765ff548b3bca403cdaa723d260" +``` + +```bash Multiple Transactions by App +curl -X GET "https://onramp.staging-portal.abs.xyz/transactions?referrer=MyApp" +``` + +```javascript Single Transaction Status +const response = await fetch( + 'https://onramp.staging-portal.abs.xyz/transactions/status?sessionId=WePzm7gRdUgis7VHQjMYYL' +); +const transaction = await response.json(); +``` + +```javascript Multiple Transactions +const response = await fetch( + 'https://onramp.staging-portal.abs.xyz/transactions?walletAddress=0xfc61f1b7701f6765ff548b3bca403cdaa723d260' +); +const transactions = await response.json(); +``` + + + + + +```json Single Transaction Response +{ + "sessionId": "WePzm7gRdUgis7VHQjMYYL", + "status": "COMPLETED", + "amount": 100, + "currency": "USD", + "destinationAmount": 68.017348, + "destinationCurrency": "USDC_BASE", + "transactionHash": "0x1234567890abcdef...", + "walletAddress": "0xfc61f1b7701f6765ff548b3bca403cdaa723d260", + "serviceProvider": "TRANSAK", + "createdAt": "2024-01-15T10:30:00Z", + "updatedAt": "2024-01-15T10:35:00Z" +} +``` + +```json Multiple Transactions Response +{ + "transactions": [ + { + "sessionId": "WePzm7gRdUgis7VHQjMYYL", + "status": "COMPLETED", + "amount": 100, + "currency": "USD", + "destinationAmount": 68.017348, + "destinationCurrency": "USDC_BASE", + "transactionHash": "0x1234567890abcdef...", + "walletAddress": "0xfc61f1b7701f6765ff548b3bca403cdaa723d260", + "serviceProvider": "TRANSAK", + "createdAt": "2024-01-15T10:30:00Z", + "updatedAt": "2024-01-15T10:35:00Z" + } + ], + "total": 1, + "page": 1, + "pageSize": 20 +} +``` + + \ No newline at end of file diff --git a/abstract-global-wallet/fiat-on-ramp/widget.mdx b/abstract-global-wallet/fiat-on-ramp/widget.mdx new file mode 100644 index 0000000..a8f48b9 --- /dev/null +++ b/abstract-global-wallet/fiat-on-ramp/widget.mdx @@ -0,0 +1,134 @@ +--- +title: "/widget" +api: "POST https://onramp.staging-portal.abs.xyz/widget" +description: "Create a session for buying crypto with FIAT currency." +--- + +Create a widget session for purchasing cryptocurrency. This generates a widget URL that users can use to complete their purchase. + +## Request Body + + + The ISO 3166 2-digit country code + + + + The code for the Crypto Currency (e.g., "ETH_BASE", "USDC_BASE") + + + + The code for the Fiat Currency (e.g., "USD", "CAD") + + + + The amount (in source currency) to buy + + + + The identifier for the Payment Method + + + + The wallet address for the user making this request (does not have to be AGW) + + + + The deposit address on Base returned in the quote + + + + Service Provider to use for this session + + + + URL to navigate back to when widget flow is complete + + + + The name of the app referring the user to the Onramp + + +## Response + + + Session identifier + + + + The name of the app referring the user to the Onramp (matches provided `referrer`) + + + + The wallet address for the user making this request (matches provided `walletAddress`) + + + + Meld generated unique identifier for your customer + + + + The crypto widget URL where users complete their purchase + + + + The session token + + + + +```bash cURL +curl -X POST "https://onramp.staging-portal.abs.xyz/widget" \ + -H "Content-Type: application/json" \ + -d '{ + "country": "US", + "destinationCurrency": "USDC_BASE", + "sourceCurrency": "USD", + "amount": "100", + "paymentMethod": "CREDIT_DEBIT_CARD", + "walletAddress": "0xfc61f1b7701f6765ff548b3bca403cdaa723d260", + "toAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", + "serviceProvider": "TRANSAK", + "redirectUrl": "https://myapp.com/success", + "referrer": "MyApp" + }' +``` + +```javascript JavaScript +const response = await fetch('https://onramp.staging-portal.abs.xyz/widget', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + country: 'US', + destinationCurrency: 'USDC_BASE', + sourceCurrency: 'USD', + amount: '100', + paymentMethod: 'CREDIT_DEBIT_CARD', + walletAddress: '0xfc61f1b7701f6765ff548b3bca403cdaa723d260', + toAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', + serviceProvider: 'TRANSAK', + redirectUrl: 'https://myapp.com/success', + referrer: 'MyApp' + }) +}); + +const widget = await response.json(); +``` + + + + + +```json Response +{ + "id": "WePzm7gRdUgis7VHQjMYYL", + "externalSessionId": "MyApp", + "externalCustomerId": "0xfc61f1b7701f6765ff548b3bca403cdaa723d260", + "customerId": "WeP9qpZzvBizvKhR8bGigL", + "widgetUrl": "https://sb.meldcrypto.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtZWxkLmlvIiwiaWF0IjoxNzUxOTUwMDM5LCJzdWIiOiJjcnlwdG8iLCJleHAiOjE3NTE5NTE4MzksImFjY291bnRJZCI6IldlUUVGcDZyZVU3VFNOQWVOODZjdFUiLCJzZXNzaW9uSWQiOiJXZVB6bTdnUmRVZ2lzN1ZIUWpNWVlMIn0.xr6V09K4ZSwYUaiOlmGVJ_QgAiaHFx9OXKvJroLGNtE", + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtZWxkLmlvIiwiaWF0IjoxNzUxOTUwMDM5LCJzdWIiOiJjcnlwdG8iLCJleHAiOjE3NTE5NTE4MzksImFjY291bnRJZCI6IldlUUVGcDZyZVU3VFNOQWVOODZjdFUiLCJzZXNzaW9uSWQiOiJXZVB6bTdnUmRVZ2lzN1ZIUWpNWVlMIn0.xr6V09K4ZSwYUaiOlmGVJ_QgAiaHFx9OXKvJroLGNtE" +} +``` + + \ No newline at end of file diff --git a/docs.json b/docs.json index 7dfb438..44e7d29 100644 --- a/docs.json +++ b/docs.json @@ -198,6 +198,18 @@ "abstract-global-wallet/agw-react/hooks/useRevokeSessions" ] }, + { + "group": "FIAT On-ramp", + "pages": [ + "abstract-global-wallet/fiat-on-ramp/overview", + "abstract-global-wallet/fiat-on-ramp/config", + "abstract-global-wallet/fiat-on-ramp/currencies", + "abstract-global-wallet/fiat-on-ramp/payment-methods", + "abstract-global-wallet/fiat-on-ramp/quote", + "abstract-global-wallet/fiat-on-ramp/widget", + "abstract-global-wallet/fiat-on-ramp/transactions" + ] + }, { "group": "Utils", "pages": [