When to use:
- NFT drops and launches
- In-game item purchases
- Digital collectible storefronts
How it works
Prerequisites
- Hub project with an environment
- ERC-721 or ERC-1155 collection deployed
Setup
Configure in Hub
Go to Hub → Primary Sales to deploy a Primary Sales contract, configure payment currencies and payout addresses, and choose between Simplified or Advanced mode.
Widget integration
- npm
- yarn
Parameters
| Parameter | Type | Description |
|---|---|---|
flow | 'SALE' | Required. Specifies the sale flow. |
items | SaleItem[] | Items to purchase. |
environmentId | string | Your Hub environment ID. |
collectionName | string | Collection name (display only). |
excludePaymentTypes | string[] | Payment methods to hide. |
Events
| Event | Description |
|---|---|
SUCCESS | Purchase completed. Payload: { transactionHash, tokens } |
FAILURE | Purchase failed. Payload: { error } |
CLOSE | User closed widget. |
Sale modes
- Simplified
- Advanced
Create and manage products directly in Hub—no backend required.Create or update a productUpserts a single product by ID (pricing, stock, metadata, linked collection and token rules, etc.). Same URL for create and update.
Pricing (
Collection (
Limits (
Example (ERC-721)Use your real collection address from Hub in place of the placeholder AuthenticationListing products is public; create, update, and delete require authentication. Authentication requires either:
Navigate to the Settings page of the project environment to create a secret API key. Do not expose secret keys in client-side code. Only manage products from your backend or Hub.Metadata for minted tokens:
- Products created in Hub are automatically available for sale
- Stock management handled by the widget
- Token IDs auto-generated for ERC-721, specified for ERC-1155
PUT replaces the entire product record for that product_id. Send a JSON object with the shape below. A successful response returns the persisted product (same fields as GET /products).Product| Field | Type | Required | Description |
|---|---|---|---|
product_id | string | Yes | Stable catalog identifier (for example starter-pack). |
name | string | Yes | Display name. |
image | string | Yes | URL for product art or icon. |
description | string | No | Longer description shown in UIs that support it. |
status | string | Yes | active or inactive. Inactive products cannot be purchased in Simplified mode. |
quantity | integer | Yes | Stock available for sale (inventory). |
pricing | array | Yes | One or more price rows (see Pricing below). At least one entry is required. |
collection | object | Yes | Which collection and token rules apply at mint (see Collection below). |
limits | object | No | Optional per-buyer caps (see Limits below). |
pricing[])Each element defines a price in one currency:| Field | Type | Required | Description |
|---|---|---|---|
currency | string | Yes | Currency code (for example USDC), aligned with currencies configured for Primary Sales. |
amount | number | Yes | Unit price in that currency for a single item. |
collection)| Field | Type | Required | Description |
|---|---|---|---|
collection_type | string | Yes | ERC721 or ERC1155. Must match how the linked collection was deployed. |
collection_address | string | Yes | NFT collection contract on chain (same collection linked to Primary Sales in Hub). |
token_id | string | ERC-1155 only | Fixed token ID for this product. Required for ERC-1155. Omit or leave unset for ERC-721 (mints use generated IDs). |
limits)| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | Yes if limits is sent | When true, per-recipient limits apply. |
max_per_recipient_address | integer | If enabled | Maximum units one wallet may purchase; must be greater than zero when limits are enabled. |
collection_address.Delete a productRemoves a product from the catalog for that environment.| Method | Header | When to use |
|---|---|---|
| Bearer token | Authorization: Bearer <access_token> | Used when managing the product catalogue via Hub |
| Secret API key | x-immutable-api-key: <secret_key> | Server-side scripts, automation, or backends using a secret API key issued for your project. |
- ERC-1155: Pre-define metadata for the Token ID before sales begin
- ERC-721: Set up a webhook in Hub for
imtbl_zkevm_activity_mintevents, then generate metadata and call the Metadata Refresh API
Webhooks (Advanced mode)
Quote
Quote
Called when a user requests a price quote for items.Endpoint:
POST {baseUrl}/quote- Request/Response
- Implementation
Request:Response:
Authorize
Authorize
Confirm
Confirm
Called after successful on-chain payment. Mint the NFTs here.Endpoint:
POST {baseUrl}/confirm- Request/Response
- Implementation
Request:Response:
Expired
Expired
Called when an authorized order expires without payment. Release reserved inventory.Endpoint:
POST {baseUrl}/expired- Request/Response
- Implementation
Request:Response:
Webhook security
Validate incoming webhooks to ensure they’re from Immutable:Payment options
Crypto
Users can pay with tokens on Immutable Chain. Default currencies are USDC and IMX. Custom ERC-20 tokens must be whitelisted. If users don’t have enough tokens, the widget offers swap, bridge, or fiat onramp options.Fiat
Users can pay with credit card, Apple Pay, or Google Pay. Funds settle to your wallet in USDC. KYC may be required for larger amounts.Limits
Next steps
Minting API
Mint NFTs from your backend
Hub Webhooks
Configure webhooks for mint events
ERC-721 Contracts
Deploy NFT collections
Orderbook
Enable secondary trading