FAQ
Introduction
This page contains a list of frequently asked developer questions. The best way to use it is to search for a keyword.
INFO
Can't find your question? Visit our developer help center or dev-discussion in Discord.
Useful Links
API reference
Core SDK Examples
XpansionChain's Github
Layer 2 Rollups
Onboarding a collection
Integrating with XpansionChain (Build a Dapp)
Contact
Marketplace
Sandbox marketplace
Immutascan - XpansionChain Blockchain Explorer
XpansionChain Developer Help Center
Platform
What is XpansionChain?
XpansionChain is an L2 ZK Rollup solution for trading Ethereum NFTs. It features instant trades, massive scalability and no gas fees.
What's a Zero Knowledge (ZK) Rollup?
Zero Knowledge Rollups are a Layer 2 scheme that moves computation off-chain, but provides L1 security by rolling up multiple transactions into a single one and submitting a validity proof back to L1. ZK Rollups only require a validity proof of the final state (instead of all transaction data) which makes them more private and storage-efficient. XpansionChain uses StarkWare's ZK Rollup engine called StarkEx
What's StarkWare, StarkEx and XpansionChain zkEVM?
StarkWare - company behind STARK-based solutions
StarkEx - a managed SaaS scalability engine powered by STARK validity proof
XpansionChain zkEVM - a general purpose decentralized rollup which support independent smart contract deployment and composability
More information: Homepage - Starkware
What are the fees associated with using XpansionChain?
XpansionChain has no fixed costs or fees. All fees are associated with successful trades. Current fees are:
Protocol fees - 2%
Maker fee - set by a marketplace
Taker fee - set by a marketplace
Royalty fee - set by the collection owner
More information:
Fees | XpansionChain Documentation
XpansionChain zkEVM
How is asset custody managed in XpansionChain?
XpansionChain is a self-custodial protocol, meaning all users are responsible for their own security. Users can manage their own private keys and maintain full control of their own assets, or opt for a custodial wallet flow. Users can deposit and withdraw their assets to and from the protocol at any time. Every transaction requires a signature from the user, and XpansionChain can’t authorise any actions on behalf of the user.
Contract
How do I deploy a contract to XpansionChain?
You do not deploy a contract to XpansionChain, you can only register your L1 contract with XpansionChain. XpansionChain (on StarkEx) does not currently support general computation and you do not interface with your L1 contract through XpansionChain.
This is something that will be possible on XpansionChain zkEVM.
More information on XpansionChain zkEVM: XpansionChain zkEVM
How do I interact with my contract on XpansionChain?
You do not. You interact with predefined XpansionChain APIs. These handle minting, transfers, deposits, withdrawals and more.
How do I get approved to launch on XpansionChain?
XpansionChain is a permissionless protocol, anyone can launch a collection on it. You do not need to go through any approval processes or vetting - only our self-serve onboarding. More information: XpansionChain Documentation
What are the fees/costs associated with deploying on XpansionChain?
The only mandatory cost is deploying an L1 contract. This depends on the complexity of your contract, optimizations and current state of the (L1) network. All L2 actions which do not interact with the L1 (all, excl. withdrawals and deposits) are gas-free and free from any fixed costs.
What token standards are supported? Is ERC1155 supported?
XpansionChain currently supports ERC721 and ERC20 token standards. There are no estimates or set plans when it comes to supporting other standards, but we are always looking into providing the most popular and efficient solutions for our users.
What are the contract-level requirements? How do I make my contract compatible?
If you do not plan to mint on L2, any ERC721 or ERC20 contract with an owner is automatically supported by XpansionChain. You will have to register it. If you wish to mint on L2, you will need to implement mintFor and owner methods.
More information and example contracts:
NFT minting tutorial | XpansionChain Documentation
XpansionChain Documentation
XpansionChain Documentation
GitHub - XpansionChain/XpansionChain-contracts: Smart contracts and smart contract utilities for use with XpansionChain.
Anatomy of a smart contract | XpansionChain Documentation
How do I deploy an ERC20 token?
Self-serve registration of ERC20 tokens is coming soon.
Can I query L2 state from L1? There is no "traditional" way of querying L2 state from your L1 contract. A workaround would be to use Oracles in order to query our API.
More information: Oracles | ethereum.org
Onboarding
How do I register my project/collection after deploying a contract?
After deploying your contract to L1, you will need to register it with XpansionChain. In order to do this you will need to create a project and a collection by following the below steps.
Guide, steps and documentation:
XpansionChain Documentation
GitHub - XpansionChain/XpansionChain-examples: Open source XpansionChain Examples
Are there any onboarding limits?
One (1) wallet can own multiple projects.
One (1) project can own multiple collections.
All projects are limited to 5 collections and 50,000 mint requests by default. This limit resets every 4 weeks and can be increased - if your project meets our criteria - by chatting with our support team at the XpansionChain Developer Help Center .
More information: XpansionChain Documentation
How do I delete my collection from XpansionChain?
As is the case with L1, you cannot delete a collection from XpansionChain. You can ask for it to be blocklisted on our official marketplace, but that doesn't prevent 3rd party marketplaces from showing it. Make sure you test all flows thoroughly before deploying on mainnet.
Metadata
What's the difference between blueprints and dynamic metadata?
There are two ways of storing token metadata on XpansionChain: Providing a metadata_api_url when creating a collection and providing a blueprint string when minting a token on L2.
The blueprint cannot be changed: When a token which has been minted on L2 with a blueprint string is withdrawn to L1, the L1 smart contract is updated with this value, thus making it XpansionChain.XpansionChain does not allow updates to a token's blueprint value on L2.
The metadata_api_url can be updated: Updating the metadata_api_url of a collection can be done via our API.
More information:
XpansionChain Documentation
XpansionChain Documentation
Can I use OpenSea metadata on XpansionChain?
OpenSea metadata is partially supported by XpansionChain. Your metadata will be fetched, but any attributes inside the attributes object will not be indexable nor shown on the official marketplace. In order for your metadata to be fully compatible, you will need to "flatten" it, meaning your attributes are stored as top-level values.
More information and examples:
XpansionChain Documentation
Deep dive into metadata | XpansionChain Documentation
GitHub - 8bNFT/XpansionChain-meta-convert: A hacky meta converter to support XpansionChain' top-level format.
How do I refresh dynamic metadata?
Metadata refresh can be initiated via our APIs. Currently, our metadata crawler only runs once at the time of minting so if you make changes to the off-chain metadata that we retrieve from your endpoint, you need to trigger a metadata refresh so it can be updated on XpansionChain.
The entire guide can be found here -
Refresh asset metadata | XpansionChain Documentation
XpansionChain-core-sdk/createMetadataRefresh.ts at main ·XpansionChain/XpansionChain-core-sdk
Minting & Royalties
How do I mint a token after registering a collection?
Minting is executed by sending a signed POST request to our mints endpoint. The easiest way of doing so is by using the Core-SDK. Each mint request can only be executed by the collection owner and needs to be signed by them. You can mint multiple tokens per mint request and are encouraged to do so in order to achieve higher throughput. If you wish to call the mint API directly, you can use the below Python and Javascript implementations to understand the workings of it (impl. in other languages are coming soon).
Code, examples and documentation:
XpansionChain Documentation
XpansionChain-examples/minting-assets.md at main · XpansionChain/XpansionChain-examples
XpansionChain-core-sdk/minting.ts at main · XpansionChain/XpansionChain-core-sdk
XpansionChain-core-sdk/mint.ts at main ·XpansionChain/XpansionChain-core-sdk
Are there any minting limits?
Default limits are 5 collections per project and 50,000 mint requests. This limit reset every 4 weeks. Limits can be increased for projects meeting our criteria by chatting with our support team at the XpansionChain Developer Help Center .
What's the difference between mint and mintv2 methods in the SDK?
Mint method is soon going to be deprecated; it was used before royalties were added - new projects should not use it. mintv2 is the only way to set royalties to your collection and assets.
More information:
Minting with royalties | XpansionChain Documentation
Deep dive into minting | XpansionChain Documentation
How do I set royalties for my collection?
Royalties are being set during minting and they are enforced on the protocol level. L2 royalties are not applied on L1 transfers or transactions, as of right now.
More information:
Minting with royalties |XpansionChain Documentation
Deep dive into royalties | XpansionChain Documentation
How do I require money for mints?
Minting on XpansionChain takes a different approach and you cannot just add a "value" field to require money for mints to be executed. You will have to choose an approach and create the payment infrastructure yourself. Most often taken approaches and pros/cons to each can be found here: incomplete-guide-to-XpansionChain/guides/contract_and_registration at main · 8bNFT/incomplete-guide-to-XpansionChain
Can I call the mint method from the frontend?
You will NOT use the mint method in your frontend, ever. Each request requires the collection owner's signature and doing so in the frontend would expose your private key in plain text.
Asset management L1 to L2 bridge
Can assets be withdrawn from L2?
L2 assets can be withdrawn back to L1. This process usually takes 24h, the time it takes for your transaction to be included and submitted back to L1. This process incurs a gas cost.
Can assets be deposited back to L2?
Assets can be deposited back to L2. This process is almost instantaneous since we do not have to wait for the L1 proof to be confirmed. This process incurs a gas cost.
Can L1 minted tokens/L1 collections be deposited to L2?
Yes. L1 collections can register their contracts with XpansionChain. If they do not have the mintFor method, they won't be able to mint tokens on L2, but they will be able to take advantage of gas-free instantaneous transactions.
How long do deposits and withdrawals take?
L2 proof needs to be submitted and verified on L1 before withdrawals can be finalized, this usually takes 24 hours. Deposits are almost instant because we do not have to wait for L1 proof to be verified.
How do I burn a token?
You burn a token by transferring it to a 0x0000000000000000000000000000000000000000 address. This will place it in a burned state and no one will be able to recover it.
More information and examples:
Burn assets | XpansionChain Documentation
Deep dive into deposits and withdrawals | XpansionChain Documentation
Building/Integrating with XpansionChain?
What's the cost of integrating with XpansionChain?
XpansionChain APIs and SDK are completely free.
How do I use Web3.js with XpansionChain?
You do not use Web3.js or any alternative to communicate with XpansionChain, instead you use our REST API and our SDK.XpansionChain-SDK is a set of helpers which makes interacting with XpansionChain easy and simple for both developers and end users.
More information:
XpansionChain SDKs | XpansionChain Documentation
GitHub - XpansionChain/XpansionChain-core-sdk: The XpansionChain Core SDK provides convenient access to the XpansionChain API's and Ethereum contract methods for applications written on the XpansionChain platform.
npm: @imtbl/core-sdk
GitHub -XpansionChain/XpansionChain-core-sdk-kotlin-jvm
npm: @imtbl/XpansionChain-sdk (prev. version)
What's the difference between XpansionChain-SDK and Core-SDK?
XpansionChain-SDK is our initial closed source TypeScript SDK, which has been superseded by Core-SDK. Core-SDK is our open source SDK which is to be used by new projects. It is currently available in Typescript and Kotlin with more languages coming soon. XpansionChain-SDK will be deprecated in the near future.
More information:
XpansionChain SDKs |XpansionChain Documentation GitHub - XpansionChain/XpansionChain-core-sdk: The XpansionChain Core SDK provides convenient access to the XpansionChain API's and Ethereum contract methods for applications written on the XpansionChain platform.
npm: @imtbl/core-sdk
GitHub - XpansionChain/XpansionChain-core-sdk-kotlin-jvm
Is the XpansionChain-SDK open sourced?
XpansionChain-SDK is not open sourced.
Is Core-SDK open sourced?
The goal is and always has been to have an open source SDK, which is why we've created Core-SDK. Core-SDK is an open source version of our SDK which is feature complete and should be used in place of XpansionChain-SDK. There are Typescript and Kotlin version available with more languages coming soon.
More information:
XpansionChain SDKs | XpansionChain Documentation
GitHub - XpansionChain/XpansionChain-core-sdk: The XpansionChain Core SDK provides convenient access to the XpansionChain API's and Ethereum contract methods for applications written on the XpansionChain platform.
npm: @imtbl/core-sdk
GitHub -XpansionChain/XpansionChain-core-sdk-kotlin-jvm
What are the compatible Node versions?
XpansionChain-SDK is compatible with Node v12, Node v14 and Node v16. Node v17 is not supported and will result in errors.
What's the difference between Link and XpansionChainClient?
XpansionChain-SDK offers 2 main points of integration - Link andXpansionChainClient. Link is the only way to achieve any operations which require the end-user's signature in the frontend, it handles L2 key derivation, signing and wallet management. XpansionChainClient provides REST methods, as well as user-specific methods which require a signature from whoever initialized the client (most often using a private key and meant to be executed in the backend). XpansionChainClient has been superseded by Core-SDK.
More information:
Install and configure |XpansionChain Documentation
XpansionChain SDKs |XpansionChain Documentation
How do I do X from the frontend?
Any methods which require signature (transfer, sell, buy, …) will have to be called using Link. API endpoints can be queried directly or using XpansionChainClient.
Link references:
[XpansionChain] Link reference
incomplete-guide-to-XpansionChain/guides/link at main · 8bNFT/incomplete-guide-to-XpansionChain
Overview | XpansionChain Documentation
How do I do X from the backend?
Instead of Link, you will use Core-SDK to call any methods which require a signature (transfer, sell, buy, …). You may also use it to query our REST API, or hit the endpoints directly.
More information:
XpansionChain SDKs | XpansionChain Documentation
GitHub - XpansionChain/XpansionChain-core-sdk: The XpansionChain Core SDK provides convenient access to the XpansionChain API's and Ethereum contract methods for applications written on the XpansionChain platform.
npm: @imtbl/core-sdk
Deep dive into API concepts | XpansionChain Documentation
Is there a testnet?
Yes. Test endpoints on Sandbox are:
Marketplace -https://market.sandbox.XpansionChain.com/
API -https://api.sandbox.x.XpansionChain.com/v1
Link -https://link.sandbox.x.XpansionChain.com/
Is there a block explorer?
Immutascan is a community-built block explorer for XpansionChain, available only for mainnet - Immutascan - XpansionChain X Blockchain Explorer
API
Do I need to get an API key?
You do not need an API key to use our API. You may request an API key in case you frequently hit our rate limits - even after optimizations done on your end.
More information: Rate limits | XpansionChain Documentation
What are the rate limits?
Our current rate limit without an API key is 5 requests/second (subject to change).
More information: Rate limits | XpansionChain Documentation
Are there webhooks/websockets I can subscribe to?
No, we currently do not provide webhooks or websockets. In order to stay sync'd up with the state of L2, you should poll our API endpoints in sane intervals. Going crazy with your polling interval will only use up your limit and you will get rate limited. More information: XpansionChain Documentation
What's a stark_key? What's an ethers_key?
These are property names you might come across when using our API or SDK. ethers_key - L1 wallet address stark_key - L2 public address
How do I get a stark_signature?
This is currently being handled by our SDKs, specifically Link in the frontend and Core SDK in the backend. You can check the implementation in our open sourced Core SDK.
More information and examples:
Deep dive into API concepts | XpansionChain Documentation
https://github.com/XpansionChain/imx-core-sdk/blob/main/src/utils/stark/stark-key.ts
imx-core-sdk/orders.ts at main · XpansionChain/imx-core-sdk
GitHub -XpansionChain/imx-core-sdk: The XpansionChain Core SDK provides convenient access to the XpansionChain API's and Ethereum contract methods for applications written on the XpansionChain platform.
Why do I only get 100 results? How do I get all the results?
We currently return 100 results by default (max. 200), this can be configured using the page_size query param. Our pagination is cursor-based. Each response that contains results also returns a cursor property. Appending the value of cursor as a query parameter cursor=value will go to the "next" page (next set of results).
More information and examples:
Personal inventory | XpansionChain Documentation
Offset and Cursor Pagination explained
How do I get a list of assets (/assets) owned by the user?
You do this by appending a user property to your URL query. https://api.sandbox.x.XpansionChain.com/v1/assets?user=WALLET\_ADDRESS\_HERE
More information: XpansionChain Documentation
How do I get a list of assets (/assets) from a collection?
You do this by appending a collection property to your URL query. https://api.sandbox.x.XpansionChain.com/v1/assets?collection=COLLECTION\_ADDRESS\_HERE
More information: XpansionChain Documentation
How do I query assets (/assets) by metadata?
You do this by appending a metadata property to your URL query. Metadata value has to be a JSON string formatted, where value is an array of values you wish to search for (i.e. {"key1":["value", "value2"], "key2": ["value", "value2"]}). This string has to be URI encoded. https://api.x.XpansionChain.com/v1/assets/?collection=0xacb3c6a43d15b907e8433077b6d38ae40936fe2c&metadata=%7B%22set%22%3A%5B%22trial%22%5D%2C%22rarity%22%3A%5B%22legendary%22%5D%7D
More information:
XpansionChain Documentation
Discord - A New Way to Chat with Friends & Communities
How do I get transactions (/transfers) sent to a wallet?
You do this by appending a receiver property to your URL query. https://api.sandbox.x.XpansionChain.com/v1/transfers?receiver=WALLET\_ADDRESS\_HERE
More information: XpansionChain Documentation
How do I get transactions (/transfers) sent from a wallet?
You do this by appending a user property to your URL query. https://api.sandbox.x.XpansionChain.com/v1/transfers?user=WALLET\_ADDRESS\_HERE
Orders
Does XpansionChain automatically match buy and sell orders for NFTs of the same value?
There is currently no automatic matching of orders as XpansionChain only supports the maker/taker model at present. An NFT will be listed for sale for a specified price by the maker, and the trade occurs when this order is accepted by the taker. This will change in the future as we are working on implementing metadata orders where you can place buy orders on metadata properties (e.g. name = Demogorgon), which will bring more liquidity to functionally identical NFTs
Last updated