The Guide

1. What this app does

You bring a folder of art. The app turns it into a finished NFT collection on Stacks (a Bitcoin layer). It can also inscribe it directly on Bitcoin (section 16) mint it on Solana (section 17), or on Ethereum and Base (section 18).

1. Numbers your pieces 0001, 0002 …
2. Gives each piece traits, a rarity tier and a story, written by an AI running on your own computer from what's actually in the picture. Or you set traits yourself.
3. Lets you review and edit every piece exactly as wallets will show it.
4. Stores the art and stories on IPFS (your own node, Pinata, or both).
5. Writes the contract, which you deploy and mint from your own wallet.

It runs only on your computer at http://127.0.0.1:8130. There's no account, no company server, and no fee to us. You pay only the normal network fees.

2. What you need

3. IPFS: where your art actually lives

This is the part most people get wrong, so it's worth two minutes.

The blockchain doesn't hold your picture. An NFT is a small record that says "token #12 belongs to this person, and its details are at this address." The picture and its story live at that address, on IPFS.

IPFS addresses files by their fingerprint (called a CID, like bafybei…). The same file always has the same CID, and any copy anywhere can answer for it. That's great, with one catch: somebody has to keep a copy online. That's called pinning. If nobody pins your files, your NFTs still exist, but every wallet shows blank boxes.

You have three choices:

4. Run your own IPFS node

Any computer that stays on works: a mini PC, an old laptop, a home server. The simplest way is Docker (install Docker), then one command:

docker run -d --name ipfs --restart unless-stopped \
  -v ipfs_data:/data/ipfs \
  -p 4001:4001 -p 4001:4001/udp \
  -p 127.0.0.1:5001:5001 \
  -p 127.0.0.1:8080:8080 \
  ipfs/kubo:latest

That's it. In the app's setup, use:

• IPFS node address (API): http://127.0.0.1:5001
• Gateway: http://127.0.0.1:8080

Node on a different computer?

Run the minter on the same machine as the node (simplest), or let the node's API listen on your home network by changing 127.0.0.1:5001:5001 to 5001:5001 and, on the node, running docker exec ipfs ipfs config Addresses.API /ip4/0.0.0.0/tcp/5001 then docker restart ipfs. Then use http://<node-ip>:5001 in the app.

Without Docker

Install Kubo from docs.ipfs.tech, then ipfs init and ipfs daemon (keep it running, or make it a service). IPFS Desktop also works and uses the same addresses.

Can the world see my node?

Wallets fetch your art from public IPFS gateways, which find your node through port 4001. Most home routers allow it automatically; if pictures don't load for others, forward TCP/UDP 4001 to the node. Or skip all of that and give your node a public web address (section 6), or add Pinata as the always-reachable copy.

5. The easy alternative: Pinata

1. Sign up at pinata.cloud. There's a free plan (check their site for the current limits; bigger collections need a paid plan).
2. Open API Keys → New Key. Give it the pinFileToIPFS permission (or Admin, simpler), name it, create it.
3. Copy the long JWT (it starts with eyJ). Pinata shows it only once.
4. Paste it in the setup wizard and press Test the key.

The key is saved only on your computer, in a file only your user can read, and it's never shown in the browser again.

6. ipfs:// links or your own gateway?

Each piece's metadata points at its picture. There are two ways to write that link:

• ipfs://bafy…/images/0001.png (recommended). This is the standard: every wallet turns it into a working link with its own gateway, and it never depends on a website of yours. Choose this with Pinata, or when your node is reachable (section 4).
• https://ipfs.yourdomain.com/ipfs/bafy…/…: through your own public gateway. Useful when your node sits at home behind a router that others can't reach. You'd put your node's gateway (port 8080) behind a web address, for example with a Cloudflare Tunnel (free, no ports to open) or a reverse proxy. The link then depends on that address staying up, but you can repoint it later (section 11).

7. AI stories and rarity (optional)

Install Ollama (free, runs on your own machine), then pull two models:

ollama pull llava          # looks at the pictures
ollama pull qwen2.5:14b    # writes the stories (smaller computer? try llama3.2)

For each piece the AI: describes what's in the picture → picks 5 traits → the app counts how rare each trait is across the whole collection → assigns one of 12 tiers (Mythic, Celestial, Divine, Legendary, Ascendant, Relic, Epic, Rare, Elite, Uncommon, Common, Base) → writes a story that fits the picture and its rarity.

It takes roughly 20–60 seconds per piece with a decent GPU. It remembers its progress, so you can stop and continue. AI makes mistakes: it may call a book a scroll or get a colour wrong. Always review in step 3.

No GPU? Use the manual option: one description for all pieces, plus trait categories with weights (e.g. Background: Gold:5, Night:30, Dawn:65). Rarer values give higher tiers.

8. What to put in each setting

Change any of these later in ⚙ Settings.

9. Making a collection, step by step

1. Collection and art: type a name, choose all your images, press Add images. They're numbered by file name, so name them in the order you want (01.png, 02.png…). Untick Replace to add more later.
2. Rarity and stories: optionally give a theme ("guardians of a fallen sky-city") and canon (facts that must stay true), then press Write rarity + stories with AI. Or use the manual option.
3. Review and edit: press Show my collection, then 👁 Preview and edit on any piece. You see it as a wallet will: name, rarity, story, traits, plus the exact metadata. Fix anything and save.
4. Store on IPFS: set the royalty and press Store on IPFS + finish the contract. This uploads the art and metadata and puts the final address into your contract. Use preview piece 1 to check.
5. Deploy and mint: opens the wallet page (next section).

Your collections are saved in ~/SonOfSatoshi-Minter/projects/<Name>/: the images, the metadata, the contract and a state.json with what you've deployed.

10. Deploy and mint

1. Connect wallet. Make sure the wallet is on the same network as the app (testnet/mainnet). The account you connect becomes the collection's owner: only it can mint or change the collection later. Use an account you'll keep (a Ledger account is ideal).
2. Deploy. Approve it in the wallet. The page waits until the network confirms, usually 1–10 minutes. Don't mint before that: the contract doesn't exist yet.
3. Mint. Mints up to 200 per approval, sent to your address. A collection of 1,000 takes 5 approvals; the page waits for each round to confirm, then offers the next. You can close it and come back; it reads the progress from the chain.

Minted NFTs appear in Xverse/Leather after the network and Hiro (the indexer wallets use) catch up, usually minutes.

11. After minting: edit, refresh, royalty, freeze

• Fix a story or picture: edit it (step 3), press Store on IPFS again (new CID), then on the mint page press Re-point and afterwards Refresh wallets.
• Refresh wallets: sends the standard "please re-read" notice (SIP-019). Use it when pictures show as blank boxes, or after a re-point. Wallets can take up to an hour to update.
• Moved your storage (new node, different gateway)? Store again, then Re-point. That's why this contract can be re-pointed: your NFTs never get stranded on a dead address.
• Royalty: change the % or who receives it.
• Freeze: locks the art and stories forever, for everyone including you. It proves to collectors that nothing will change. Only do it once everything is final and your storage is solid.

12. Keep a backup

Copy ~/SonOfSatoshi-Minter/projects/ somewhere safe (an external drive, a NAS). With those files you can put your art back on any IPFS node at the exact same CIDs, because IPFS addresses files by content. Your NFTs work again without touching the blockchain. The folder is the master copy of your work.

13. Costs

This app is free. You pay the Stacks network's fees, set by your wallet and usually small (a fraction of an STX to a few STX): one fee to deploy, one per mint round of up to 200, one per re-point / refresh / royalty change.

Practice for free on testnet: switch your wallet to Testnet, copy your ST… address, and request test STX at the Hiro faucet.

14. Safety

• This app never asks for your secret words (seed phrase) or private key. If anything ever does, stop.
• Every transaction opens in your wallet: read it before approving. The mint page shows the full contract code.
• Every request is sent in "Deny" mode: your wallet will refuse anything that would move STX or NFTs out of your account.
• The contract fixes the collection size forever. Nobody, not even you, can mint extra pieces later, which is something collectors can check.
• The app only answers on 127.0.0.1 (your own computer) and refuses requests from other websites.
• Your Pinata key is stored only in ~/SonOfSatoshi-Minter/config.json, readable only by you.
• Don't expose your IPFS node's port 5001 to the internet (section 4).

15. When something goes wrong

16. Bitcoin Ordinals: inscribe on Bitcoin itself

Instead of Stacks, you can inscribe your collection directly onto Bitcoin as Ordinals. The art and its story are written into Bitcoin transactions, so they live on-chain forever: no IPFS, no gateway, nothing to keep online, nothing that can go blank. Choose Bitcoin Ordinals on the first question of the setup (or in ⚙ Settings).

What's different from Stacks

• You pay by the byte. Every byte of the image goes on-chain. A 2 MB PNG can cost hundreds of dollars; a well-compressed WebP of 30–80 KB costs a small fraction and looks the same on a phone. The Inscribe page shows the exact cost of every piece and compresses them all with one button (you choose the size and quality).
• It's permanent. There's no re-point, no edit and no freeze: what you inscribe is final. Review everything first.
• No contract, no royalties. Each piece is its own inscription. Marketplaces group them into a collection from the collection file the app makes for you (step 4 of the Inscribe page).
• The story and traits can go on-chain with the art, as the inscription's metadata (a checkbox on the Inscribe page).

What you need

• An ordinals-aware wallet (Xverse or Leather). Give the app its Ordinals address (taproot, starts with bc1p, or tb1p on testnet). Never send inscriptions to an ordinary wallet: it can spend them as fees without warning.
• A refund address: any address of yours. Leftover coins come back there.
• A data source: mempool.space (nothing to run), your own mempool/esplora server, or your own Bitcoin Core node (fully sovereign: give its RPC address, user and password; it's used to read the chain and to send your transactions).

How inscribing works

1. Prepare: pick a fee rate, compress the pieces if you want, and check the total.
2. Create the batch: the app makes a temporary key for this batch and saves it on your computer before showing you anything, then shows ONE address and an exact amount. Pay it from any wallet.
3. Commit: once your payment arrives, the app splits it into one output per piece and sends that transaction.
4. Reveal: after the commit confirms (about 10 minutes), it writes each piece in its own transaction and sends the inscribed sat (546 sats of "postage") to your Ordinals address.

You can close the page at any time: it picks up where it stopped. Up to 50 pieces per batch; bigger collections use several.

If something goes wrong

• Changed your mind before the commit? Press Recover funds: everything on the funding address goes back to your refund address.
• Paid too little? Send the rest to the same address; the page adds it up. Paid too much? The extra comes back to your refund address automatically.
• After the commit, the money can only continue into the inscriptions: that's the recovery, and the app does it by itself when you reopen the page. The temporary keys live in ~/SonOfSatoshi-Minter/projects/<Name>/ordinals/batches/ (readable only by you). Back that folder up and never share it.

Practice first

Choose Testnet4 in the setup, switch Xverse to Testnet4, and get free test coins from a testnet4 faucet (for example mempool.space's). Inscribe a couple of small pieces end to end before spending real bitcoin.

17. Solana (Metaplex Core)

Choose Solana on the first question of the setup (or in ⚙ Settings). Your collection becomes a Metaplex Core collection, the current standard on Solana: one collection account holds the name, the picture and the royalty rule, and every piece is a Core asset inside it. Magic Eden, Tensor and the main wallets show Core collections.

What you need

• A Solana wallet as a browser extension: Phantom, Solflare or Backpack. A Ledger works through them.
• A place for the art on IPFS, exactly as for Stacks (your node, Pinata, or both). Solana wallets need https links, so the links go through your public gateway if you set one, otherwise through ipfs.io.
• Some SOL. Each piece costs about 0.004 SOL: mostly a deposit (rent) that keeps its account on Solana, plus Metaplex's 0.0015 SOL creation fee and a tiny network fee. The collection itself costs about 0.003 SOL once. The mint page shows the exact estimate before you start.
• Optional: your own RPC address. The free public ones are slow and rate-limited; for a big mainnet collection a free account at an RPC provider or your own node is smoother. It stays on your computer (the page talks only to the app, and the app passes on just the calls minting needs).

Minting, step by step

1. Build and Store the collection on the main page, as usual.
2. Open Go to mint on Solana and connect your wallet.
3. Create the collection: set the royalty % and who receives it (blank = the connected wallet). One approval.
4. Mint: choose the range and how many pieces per approval (24 is comfortable). Your wallet approves a whole batch in one prompt; about three pieces fit in each transaction. Every signed transaction is saved before it's sent: if the page closes, reopen it and the app checks what landed, records it, and skips those pieces next time. Nothing is ever minted twice.

After minting

• Re-point: edited a story or a picture? Store again on the main page, then press Re-point: the collection and every minted piece switch to the new links (the list shows which pieces still point at an older version).
• Royalty: change the % or the receiver any time.
• Lock forever: adds Metaplex's ImmutableMetadata to the collection. After that nobody, you included, can change a name or link of the collection or any piece in it. The royalty can still change.

Practice first

Choose Devnet in the setup, and switch your wallet to Devnet too (in Phantom: turn on testnet mode in its developer settings and pick Solana Devnet; Solflare and Backpack have the same switch). Get free devnet SOL with the Get 2 free test SOL button on the mint page, or at faucet.solana.com. Mint a few pieces end to end before using real SOL. Devnet and mainnet records are kept apart, so practice never mixes with the real collection.

Developers: a local solana-test-validator works too (network "My own local validator"). Load Metaplex Core into it with solana program dump -u m CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d mpl_core.so and solana-test-validator --bpf-program CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d mpl_core.so.

18. Ethereum and Base

Choose Ethereum / Base on the first question of the setup (or in ⚙ Settings). Each collection gets its own ERC-721 contract, which you deploy and own. Base is a layer built on Ethereum, run by Coinbase, with the same wallets and addresses but fees of cents instead of dollars. OpenSea and the main wallets show both.

What you need

• A browser wallet: MetaMask, Rabby, Coinbase Wallet or any other. A Ledger works through them. There's nothing else to set up: the page talks to the network through your wallet and asks it to switch to the right network (adding it if needed).
• A place for the art on IPFS, exactly as for Stacks. ipfs:// links work on OpenSea and in wallets; use your public gateway if your node is at home behind a router (see section 6).
• Some ETH on the network you chose. Deploying uses about 1.7 million gas and each piece about 30 thousand. On Base a whole collection usually costs well under a few dollars; on Ethereum the deploy alone can cost from a few to tens of dollars, depending on how busy the network is. The page shows the exact estimate before each step.

The contract

• Fixed supply: the number of pieces is set at deploy and can never grow.
• Only you mint, in numbered batches. Each batch says which number it starts at, so the contract refuses one that was already minted: a page that closed, a double click or a replayed transaction can never mint extra pieces.
• Links: each piece's link is the base link + its number + ".json". You can re-point the base (one transaction for all pieces, and marketplaces are told to refresh) until you freeze it, which is permanent.
• Royalty (ERC-2981): up to 30%, to any address, changeable any time. Marketplaces decide whether they pay it.
• The code is contracts/SonOfSatoshiCollection.sol (OpenZeppelin 5.6.1, compiler 0.8.37, optimizer 200 runs, EVM cancun). To show it as "verified" on Etherscan or Basescan: on your contract's page choose Verify and Publish → Solidity (Standard-Json-Input), compiler v0.8.37, and upload contracts/SonOfSatoshiCollection.verify.json from the app's folder. Etherscan usually detects the constructor arguments by itself.

Minting, step by step

1. Build and Store the collection on the main page, as usual.
2. Open Go to mint and connect your wallet.
3. Deploy: pick a short symbol, the royalty % and who receives it. One approval. The connected wallet becomes the owner.
4. Mint: choose how many pieces per transaction (100 on Ethereum, 150 on Base are comfortable) and who receives them. One approval per batch; the page keeps going until every piece is out. If anything stops, press Mint again: it carries on from where the chain is.

Practice first

Choose Base Sepolia (or Sepolia) in the setup. Get free test ETH from a faucet (Coinbase's developer platform and Alchemy both run one for Base Sepolia and Sepolia). Deploy and mint a few pieces end to end before using real ETH. Practice records are kept apart from the real networks'.