NFT Marketplace
A multi-chain NFT marketplace addon for Bicrypto — collections, ERC-721/ERC-1155 minting, fixed-price sales, auctions, offers, royalties and moderation. Requires Bicrypto core and the Ecosystem addon.
The NFT Marketplace addon turns a Bicrypto install into a multi-chain NFT marketplace. Creators register a collection, deploy an ERC-721 or ERC-1155 contract to a supported chain, mint tokens from their own wallet, and list them at a fixed price, as a timed auction, or as a bundle. Buyers purchase directly, bid, or make an offer that sits in escrow until the seller accepts it.
It ships 75 user-facing API routes, 46 admin routes, 21 database tables, 15 admin screens and three scheduled jobs. This documentation covers the parts you have to make a decision about.
It requires Bicrypto core and the Ecosystem addon. Ecosystem is not a
recommendation — every contract deployment, every on-chain purchase and every
auction settlement signs with an Ecosystem master wallet and reads its RPC
provider and contract ABIs from Ecosystem's modules. Without it,
deployMarketplace throws "Ecosystem extension is required for NFT
marketplace deployment" and nothing else in the product can start.
See Install for what has to be true before you activate it.
The one thing to understand first
Money moves along two completely different paths depending on how the sale happened, and they are not interchangeable.
| Sale type | Where the money is | Who pays the seller |
|---|---|---|
| Fixed-price purchase | On chain. The buyer signs and broadcasts the payment themselves. | The marketplace contract, or a direct wallet-to-wallet transfer |
| Auction | On chain, held by a per-listing NFTAuction contract |
The auction contract, at endAuction |
| Offer | Custodial. Held in the buyer's SPOT wallet on your platform | The platform, at confirmation, from that escrow |
A fixed-price sale never touches a Bicrypto wallet balance — the platform
verifies the transaction hash and records a nft_sale row. An accepted offer
never touches the chain for payment — the buyer's SPOT balance is placed on
hold when the offer is made and split three ways when the transfer is
confirmed.
The practical consequence: your marketplace fee accumulates in two separate
places. On-chain fees pile up inside the marketplace contract and have to be
withdrawn deliberately; offer fees land in the Super Admin wallet as
adminProfit rows of type NFT_SALE. Fees and
royalties explains both.
What operators control
- Chain availability. A chain only appears to users once you have deployed
a marketplace contract on it.
/api/nft/chainsis derived from thenft_marketplacetable, and collection creation refuses any chain with no ACTIVE row. - Collection approval. Every user-created collection is written with
status: "PENDING". Until an admin flips it to ACTIVE nobody can mint into it. - Fees and royalties. A platform fee percentage, a maximum creator royalty the whole product clamps to, and a flat listing fee.
- Which trade types exist. Fixed price, auctions and offers each have their own on/off switch.
- Auction mechanics. Minimum and maximum duration, minimum bid increment as a percentage, anti-snipe extension.
- KYC gates. Six NFT actions (
view_nft,create_nft,buy_nft,sell_nft,transfer_nft,deploy_nft_contract) can each be tied to a KYC level. - Moderation. Collections, tokens, listings, offers, auctions and creator profiles can each be disabled from the admin panel; disputes have a full queue with priorities, assignment and a message thread.
What operators do not control
Worth knowing before you promise anything to a customer:
- Nobody mints on a user's behalf. There is no custodial signer. Every mint is signed by the creator's own browser wallet and then reported to the backend, which verifies the receipt before it writes a token row. That is why batch minting creates DRAFT rows and refuses to put them on chain.
- Media is not hosted. Creators supply their own IPFS URL for the image and, optionally, for the metadata JSON. There is no upload-to-IPFS pipeline in the product.
- The royalty ledger is dormant.
nft_royaltyhas a PENDING/PAID/FAILED lifecycle and nothing writes to it. Royalties are paid in cash at settlement time, so there is no debt to track. nft_sale.statusis alwaysCOMPLETED. All four insert sites write that value; PENDING and FAILED are unreachable.
How it fits the platform
The tables ship in initial.sql, so a fresh core install already has
nft_collection, nft_token, nft_listing and the rest — activating the
extension exposes the routes and menus rather than creating the schema. Two
later tables, nft_metadata_backup and gas_history, are created by the boot
sync instead.
Three cron jobs run in the nft category and are visible on the admin cron
screen: expireOffers every 5 minutes, settleAuctions every 10 minutes, and
processNFTBackups every 15 minutes. If your cron process is not running,
offers never expire and auctions never pay out.
Where to start
Ecosystem prerequisites, licence activation, the first marketplace contract, categories, and the settings you must set before you let anyone in.
How a collection is created, approved and deployed, and why the contract address is the gate on nearly everything else.
The six-step wizard, IPFS requirements, the duplicate check, batch preparation, and what the backend verifies before it writes a token.
Listings, direct purchases, auctions with anti-snipe, and the two-step offer flow with its 24-hour unwind.
Where each percentage is read, where it is clamped, and the two places your revenue accumulates.
The moderation console, the fifteen screens, and which queue answers which question.
Two reference pages sit behind those: Settings lists every key the product reads with its default and its real effect, and Permissions and endpoints maps every permission key to the screen and the route it gates. When something is stuck, start at Troubleshooting.