|
1 | 1 | --- |
2 | 2 | title: useBuyModal |
3 | | -description: El hook useBuyModal permite a los usuarios comprar un NFT que está listado en el Marketplace. Se encarga del proceso de compra y la ejecución de la transacción. |
| 3 | +description: Hook para gestionar la interfaz del modal de compra de coleccionables |
4 | 4 | sidebarTitle: useBuyModal |
5 | 5 | --- |
6 | 6 |
|
7 | | -```ts |
8 | | -import { useBuyModal } from "@0xsequence/marketplace-sdk/react"; |
| 7 | +## Importar |
9 | 8 |
|
10 | | -## Into your React component: |
11 | | - |
12 | | -const { show: showBuyModal } = useBuyModal({ |
13 | | - onSuccess(hash) { |
14 | | - console.log("Buy transaction sent with hash: ", hash); |
15 | | - }, |
16 | | - onError, |
17 | | -}); |
18 | | - |
19 | | -const onClickBuy = () => { |
20 | | - showBuyModal({ |
21 | | - chainId, |
22 | | - collectionAddress, |
23 | | - tokenId, |
24 | | - order, |
25 | | - }); |
26 | | -}; |
27 | | - |
28 | | -return <button onClick={onClickBuy}>Buy</button> |
| 9 | +```tsx |
| 10 | +import { useBuyModal } from "@0xsequence/marketplace-sdk/react"; |
29 | 11 | ``` |
30 | 12 |
|
31 | | -<ResponseField name="useBuyModal"> |
32 | | - <ResponseField name="* params" /> |
33 | | - |
34 | | - <Expandable> |
35 | | - ```ts |
36 | | - interface useBuyModal { |
37 | | - onSuccess?: ({ hash, orderId }: { |
38 | | - hash?: Hash; |
39 | | - orderId?: string; |
40 | | - }) => void; |
41 | | - onError?: (error: Error) => void; |
| 13 | +## Uso |
| 14 | + |
| 15 | +### Examples |
| 16 | + |
| 17 | +<Tabs> |
| 18 | + <Tab title="Compra en el mercado"> |
| 19 | + Ejemplo de cómo implementar una compra en el mercado (ventas secundarias) usando el hook `useBuyModal`: |
| 20 | + |
| 21 | + <Note> |
| 22 | + Este ejemplo utiliza el hook [`useLowestListing`](/sdk/marketplace-sdk/hooks/marketplace-data/useLowestListing) de marketplace-sdk. Si no existe un lowestListing con los parámetros indicados, significa que no hay un orderId disponible y, por lo tanto, el artículo no se puede comprar. |
| 23 | + </Note> |
| 24 | + |
| 25 | + ```tsx |
| 26 | + |
| 27 | + import type { MarketplaceKind } from "@0xsequence/marketplace-sdk"; |
| 28 | + import { |
| 29 | + useBuyModal, |
| 30 | + useLowestListing, |
| 31 | + } from "@0xsequence/marketplace-sdk/react"; |
| 32 | + import type { Address } from "viem"; |
| 33 | + |
| 34 | + export default function MarketPurchaseExample() { |
| 35 | + const { |
| 36 | + data: lowestListing, |
| 37 | + isLoading: isLoadingLowestListing, |
| 38 | + isError: isErrorLowestListing, |
| 39 | + } = useLowestListing({ |
| 40 | + collectionAddress: "0x1234567890123456789012345678901234567890" as Address // Replace with your collection address |
| 41 | + chainId: 1 // Replace with your chain id |
| 42 | + tokenId: "1", // Replace with your token id |
| 43 | + }); |
| 44 | + const chainId = lowestListing?.chainId as number; |
| 45 | + const collectionAddress = lowestListing?.collectionContractAddress as Address; |
| 46 | + const tokenId = lowestListing?.tokenId as string; |
| 47 | + const orderId = lowestListing?.orderId as string; |
| 48 | + const marketplace = lowestListing?.marketplace as MarketplaceKind; |
| 49 | + const priceUSDFormatted = lowestListing?.priceUSDFormatted as string; |
| 50 | + |
| 51 | + const { show: showMarketModal } = useBuyModal({ |
| 52 | + onSuccess: ({ hash, orderId }) => { |
| 53 | + console.log("Market purchase successful", { hash, orderId }); |
| 54 | + }, |
| 55 | + onError: (error) => { |
| 56 | + console.error("Market purchase failed:", error.message); |
| 57 | + }, |
| 58 | + }); |
| 59 | + |
| 60 | + const handleMarketBuy = () => { |
| 61 | + if (!lowestListing || isLoadingLowestListing) return; |
| 62 | + |
| 63 | + showMarketModal({ |
| 64 | + chainId, |
| 65 | + collectionAddress, |
| 66 | + collectibleId: tokenId, |
| 67 | + orderId, |
| 68 | + marketplace, |
| 69 | + }); |
| 70 | + |
| 71 | + }; |
| 72 | + |
| 73 | + return ( |
| 74 | + <div style={{ padding: "20px" }}> |
| 75 | + <h3>Market Purchase</h3> |
| 76 | + |
| 77 | + <p>Price: ${priceUSDFormatted}</p> |
| 78 | + |
| 79 | + <button |
| 80 | + onClick={handleMarketBuy} |
| 81 | + disabled={isLoadingLowestListing || isErrorLowestListing} |
| 82 | + > |
| 83 | + Buy from Market |
| 84 | + </button> |
| 85 | + </div> |
| 86 | + |
| 87 | + ); |
| 88 | + } |
| 89 | + |
| 90 | + ``` |
| 91 | + </Tab> |
| 92 | + |
| 93 | + <Tab title="Compra en la tienda"> |
| 94 | + Ejemplo de cómo implementar una compra en la tienda (ventas primarias) usando el hook `useBuyModal`: |
| 95 | + |
| 96 | + <Note> |
| 97 | + Este ejemplo utiliza el hook [`useListPrimarySaleItems`](/sdk/marketplace-sdk/hooks/marketplace-data/useListPrimarySaleItems) de marketplace-sdk. El hook obtiene los artículos de venta primaria de un contrato específico. Si no existe un primarySaleItem con los parámetros indicados o si el suministro es 0, el artículo no se puede comprar. |
| 98 | + </Note> |
| 99 | + |
| 100 | + ```tsx |
| 101 | + |
| 102 | + import { |
| 103 | + useBuyModal, |
| 104 | + useListPrimarySaleItems, |
| 105 | + } from '@0xsequence/marketplace-sdk/react'; |
| 106 | + import type { Address } from 'viem'; |
| 107 | + |
| 108 | + export default function ShopPurchaseExample() { |
| 109 | + // Example values - replace with your own |
| 110 | + const chainId = 1; // Ethereum mainnet |
| 111 | + const saleContractAddress = |
| 112 | + '0x1234567890123456789012345678901234567890' as Address; |
| 113 | + const collectionAddress = |
| 114 | + '0x0987654321098765432109876543210987654321' as Address; |
| 115 | + const tokenId = '1'; |
| 116 | + |
| 117 | + const { show: showBuyModal } = useBuyModal({ |
| 118 | + onSuccess: ({ hash }) => { |
| 119 | + console.log('Shop purchase successful', { hash }); |
| 120 | + }, |
| 121 | + onError: (error) => { |
| 122 | + console.error('Shop purchase failed:', error.message); |
| 123 | + }, |
| 124 | + }); |
| 125 | + |
| 126 | + // Fetch primary sale items - replace parameters with your own |
| 127 | + const { data: primarySaleItems } = useListPrimarySaleItems({ |
| 128 | + chainId: chainId, |
| 129 | + primarySaleContractAddress: saleContractAddress, |
| 130 | + filter: { |
| 131 | + includeEmpty: true, |
| 132 | + }, |
| 133 | + }); |
| 134 | + |
| 135 | + const primarySaleItem = |
| 136 | + primarySaleItems?.pages[0]?.primarySaleItems[0]?.primarySaleItem; |
| 137 | + |
| 138 | + const handleShopBuy = () => { |
| 139 | + if (!primarySaleItem) return; |
| 140 | + |
| 141 | + showBuyModal({ |
| 142 | + chainId: chainId, |
| 143 | + collectionAddress: collectionAddress, |
| 144 | + salesContractAddress: saleContractAddress, |
| 145 | + marketplaceType: 'shop', |
| 146 | + quantityDecimals: 0, |
| 147 | + quantityRemaining: Number(primarySaleItem.supply), |
| 148 | + items: [ |
| 149 | + { |
| 150 | + tokenId: tokenId, |
| 151 | + quantity: '1', |
| 152 | + }, |
| 153 | + ], |
| 154 | + salePrice: { |
| 155 | + amount: primarySaleItem.priceAmount ?? '0', |
| 156 | + currencyAddress: (primarySaleItem.currencyAddress as Address) ?? '0x', |
| 157 | + }, |
| 158 | + }); |
| 159 | + |
| 160 | + }; |
| 161 | + |
| 162 | + return ( |
| 163 | + <div> |
| 164 | + <p>Available: {primarySaleItem?.supply ?? 0}</p> |
| 165 | + <button |
| 166 | + onClick={handleShopBuy} |
| 167 | + disabled={!primarySaleItem || Number(primarySaleItem.supply) === 0} > |
| 168 | + Buy from Shop |
| 169 | + </button> |
| 170 | + </div> |
| 171 | + ); |
42 | 172 | } |
| 173 | + |
43 | 174 | ``` |
44 | | - </Expandable> |
45 | | - |
46 | | - <ResponseField name="* return properties" /> |
47 | | - |
48 | | - <Expandable> |
49 | | - <ResponseField name="show" type="(args: ShowBuyModalArgs) => void"> |
50 | | - ```ts |
51 | | - interface ShowBuyModalArgs { |
52 | | - chainId: string; |
53 | | - collectionAddress: Hex; |
54 | | - tokenId: string; |
55 | | - order: Order; |
56 | | - } |
57 | | - ``` |
58 | | - </ResponseField> |
59 | | - |
60 | | - <ResponseField name="close" type="() => void" /> |
61 | | - </Expandable> |
62 | | -</ResponseField> |
| 175 | + </Tab> |
| 176 | +</Tabs> |
| 177 | + |
| 178 | +## Parámetros |
| 179 | +El hook acepta un objeto opcional `callbacks` con las siguientes propiedades: |
| 180 | + |
| 181 | +```tsx |
| 182 | +interface ModalCallbacks { |
| 183 | + onSuccess?: ({ hash, orderId }: { hash?: Hash; orderId?: string }) => void; |
| 184 | + onError?: (error: Error) => void; |
| 185 | + successActionButtons?: Array<{ label: string; action: () => void }>; |
| 186 | +} |
| 187 | +``` |
| 188 | + |
| 189 | +| Parámetro | Type | Description | |
| 190 | +| -------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------- | |
| 191 | +| `callbacks.onSuccess` | `({ hash, orderId }: { hash?: Hash; orderId?: string }) => void` | Función de callback opcional que se llama cuando la compra es exitosa | |
| 192 | +| `callbacks.onError` | `(error: Error) => void` | Función de callback opcional que se llama cuando ocurre un error durante la compra | |
| 193 | +| `callbacks.successActionButtons` | `Array<{ label: string; action: () => void }>` | Arreglo opcional de botones de acción para mostrar en caso de éxito | |
| 194 | + |
| 195 | +## Tipo de retorno |
| 196 | +El hook retorna un objeto con los siguientes métodos: |
| 197 | + |
| 198 | +```tsx |
| 199 | +{ |
| 200 | + show: (args: BuyModalProps) => void |
| 201 | + close: () => void |
| 202 | +} |
| 203 | +``` |
| 204 | + |
| 205 | +### Métodos |
| 206 | + |
| 207 | +#### show |
| 208 | +`(args: BuyModalProps) => void` |
| 209 | + |
| 210 | +Abre el modal de compra con los parámetros especificados. `BuyModalProps` puede ser `ShopBuyModalProps` o `MarketplaceBuyModalProps` dependiendo del tipo de compra. |
| 211 | + |
| 212 | +Para compras en el mercado (ventas secundarias): |
| 213 | + |
| 214 | +```tsx |
| 215 | +interface MarketplaceBuyModalProps extends BuyModalBaseProps { |
| 216 | + marketplaceType?: "market"; |
| 217 | + collectibleId: string; |
| 218 | + marketplace: MarketplaceKind; |
| 219 | + orderId: string; |
| 220 | +} |
| 221 | +``` |
| 222 | + |
| 223 | +Para compras en la tienda (ventas primarias): |
| 224 | + |
| 225 | +```tsx |
| 226 | +interface ShopBuyModalProps extends BuyModalBaseProps { |
| 227 | + marketplaceType: "shop"; |
| 228 | + salesContractAddress: Address; |
| 229 | + items: Array<Partial<CheckoutOptionsItem> & { tokenId?: string }>; |
| 230 | + quantityDecimals: number; |
| 231 | + quantityRemaining: number; |
| 232 | + salePrice: { |
| 233 | + amount: string; |
| 234 | + currencyAddress: Address; |
| 235 | + }; |
| 236 | + unlimitedSupply?: boolean; |
| 237 | +} |
| 238 | +``` |
| 239 | + |
| 240 | +Ambos tipos extienden de `BuyModalBaseProps`: |
| 241 | + |
| 242 | +```tsx |
| 243 | +interface BuyModalBaseProps { |
| 244 | + chainId: number; |
| 245 | + collectionAddress: Address; |
| 246 | + skipNativeBalanceCheck?: boolean; |
| 247 | + nativeTokenAddress?: Address; |
| 248 | + marketplaceType?: MarketplaceType; |
| 249 | + customCreditCardProviderCallback?: (buyStep: Step) => void; |
| 250 | + successActionButtons?: Array<{ label: string; action: () => void }>; |
| 251 | +} |
| 252 | +``` |
| 253 | + |
| 254 | +#### close |
| 255 | +`() => void` |
| 256 | + |
| 257 | +Cierra el modal de compra. |
| 258 | + |
| 259 | +## Notas |
| 260 | +El hook `useBuyModal` ofrece una forma práctica de gestionar la interfaz del modal de compra de coleccionables. Se encarga de: |
| 261 | +- Abrir y cerrar el modal |
| 262 | +- Gestionar el estado del flujo de compra |
| 263 | +- Manejo de errores y callbacks de éxito |
| 264 | +- Soporte tanto para ventas primarias como secundarias |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments