bot-mint-opensea

Local-only OpenSea mint bot for personal use.

This bot watches OpenSea collection slugs from watchlist.json, checks whether a public Ethereum drop stage is currently live, blocks mints above your configured maxPriceEth, and prints timestamped logs for each decision.

Features

• watches OpenSea drop collections by slug
• supports ethereum only in v1
• only mints public_sale stages
• supports strict free mint only mode
• blocks mint attempts above maxPriceEth
• blocks mint attempts when final transaction value exceeds the allowed cap
• validates that rpcUrl points to Ethereum mainnet in live mode
• uses OPENSEA_API_KEY from .env first
• supports --dry-run mode for safe simulation
• prevents repeated successful mints for the same slug in one bot session
• never logs the private key

What --dry-run Means

--dry-run is simulation mode.

In dry-run mode, the bot:

• loads config
• checks the collection
• reads drop stages
• detects whether a public mint is live
• logs what it would do

In dry-run mode, the bot does not:

• sign transactions
• send transactions
• mint NFTs

Use dry-run to safely test:

• whether the slug is correct
• whether the public mint is detected
• whether the mint price is really free
• whether the bot logs look correct

Requirements

• Bun
• global @opensea/cli
• an Ethereum mainnet RPC URL from Alchemy, QuickNode, Infura, or Ankr
• an OpenSea API key
• a local pk.txt file for live mode

Install

bun install

Setup

1. Create .env

OPENSEA_API_KEY=your_opensea_api_key

2. Create pk.txt

0xyour_private_key_here

Notes:

• pk.txt is local-only and ignored by git
• never share your private key
• the wallet still needs ETH for gas, even for free mints

3. Create watchlist.json

Example for a free mint target:

{
  "pollIntervalMs": 3000,
  "rpcUrl": "https://eth-mainnet.g.alchemy.com/v2/YOUR_RPC_KEY",
  "gas": {
    "mode": "preset",
    "preset": "normal"
  },
  "collections": [
    {
      "slug": "theoremnft-official",
      "chain": "ethereum",
      "enabled": true,
      "maxPriceEth": 0,
      "quantity": 1
    }
  ]
}

Field meanings:

• pollIntervalMs: polling interval in milliseconds
• rpcUrl: Ethereum mainnet RPC URL
• gas: top-level gas config for Ethereum transactions
• gas.mode: auto, manual, or preset
• gas.preset: one of slow, normal, fast, turbo when mode is preset
• gas.maxFeePerGasGwei: required when mode is manual
• gas.maxPriorityFeePerGasGwei: required when mode is manual
• gas.gasLimit: optional when mode is manual
• slug: OpenSea collection slug
• chain: must be ethereum
• enabled: enables or disables the target
• maxPriceEth: maximum allowed mint price
• quantity: mint quantity

Gas modes:

• auto: let the provider estimate gas fields
• manual: use the exact maxFeePerGasGwei and maxPriorityFeePerGasGwei values you provide, with optional gasLimit
• preset: use one of the built-in presets

Preset values:

• slow: 15 / 1 gwei
• normal: 25 / 2 gwei
• fast: 40 / 3 gwei
• turbo: 60 / 5 gwei

Commands

Run tests:

bun test

Run typecheck:

bun run check

Run dry-run:

bun run index.ts --dry-run

Run live mode:

bun run index.ts

Recommended Usage

Before mint goes live

Run dry-run 10-15 minutes before the mint window:

bun run index.ts --dry-run

Expected behavior:

• before public mint is live: no live public mint
• once public mint is detected: dry-run mint preview

When mint is live

If dry-run shows the correct collection and expected price, stop dry-run and start live mode:

bun run index.ts

Live mode will:

• load the wallet
• build mint transaction data
• sign the transaction
• broadcast the transaction

Important Logs

• opensea api key source selected source="env" The bot is using the API key from .env.

• watchlist loaded The config was loaded successfully.

• gas mode selected The bot loaded your selected gas mode and, for manual or preset, logs the effective values.

• wallet loaded The wallet is ready for live mode.

• checking collection The bot is currently checking the configured slug.

• no live public mint No active public mint was found yet.

• dry-run mint preview A mintable public stage was detected, but no transaction was sent because this is simulation mode.

• mint blocked by max price The detected stage price is above the configured maxPriceEth.

• mint blocked by total price The final mint transaction value is higher than the allowed cap.

• mint submitted The transaction was signed and sent successfully.

Free Mint Configuration

For strict free mint only mode, use:

"maxPriceEth": 0

This means the bot will only proceed if:

• the detected stage price is free
• the final transaction value is also 0

Note:

• free mint still requires ETH for gas

Safety Rules

• do not run multiple bot instances at the same time
• do not share .env or pk.txt
• always test with --dry-run first
• keep quantity within the collection's wallet limit
• only use live mode when you are ready to send a real transaction

Troubleshooting

Failed to create OpenSea API key: 429

The bot was trying to create a new instant key too often. Current startup should prefer OPENSEA_API_KEY from .env.

rpcUrl is required in live mode

Add rpcUrl to watchlist.json.

pk.txt must contain a 32-byte hex private key

Your private key format is invalid.

no live public mint

This is normal before the public mint is active.

Current Example Target

The bot has been tested against:

• slug: theoremnft-official
• chain: ethereum
• public price target: 0.00 ETH
• quantity: 1