dropcast-cli

CLI + Agent Skill for creating DropCast airdrop campaigns on Base.

WARNING: The default API URL (https://dropcast.xyz) is production. All --execute commands create real campaigns with real funds.

Install

# Run directly
npx dropcast-cli --help

# Or install globally
npm install -g dropcast-cli

Requires Node.js >= 18.

Quickstart

1. Copy an example config:

cp examples/campaign.farcaster.pool-split.json campaign.json

2. Edit campaign.json with your campaign details (FID, wallet, post URL, token, reward amounts, etc.).

3. Validate offline (schema only, no network):

dropcast-cli validate --config campaign.json --offline

4. Dry-run (resolves cast, fetches prices, checks balances -- no transactions):

dropcast-cli create --config campaign.json

5. Execute (when ready -- sends real transactions):

dropcast-cli create --config campaign.json --execute

Configuration Reference

Campaign configs are JSON files validated against a Zod schema. See examples/ for complete samples.

Top-level fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | network | "base" | Yes | Only Base Mainnet is supported | | platform | "farcaster" | "x" | Yes | Target platform |

host

| Field | Type | Required | Description | |-------|------|----------|-------------| | fid | integer | Yes | Host's Farcaster FID | | walletAddress | string | Yes | Host's wallet address (0x-prefixed, 40 hex chars). Must match PRIVATE_KEY wallet for --execute |

post

| Field | Type | Required | Description | |-------|------|----------|-------------| | url | string (URL) | Yes | Farcaster post URL or tweet URL (X) |

token

| Field | Type | Required | Description | |-------|------|----------|-------------| | address | string | Yes | ERC-20 token contract address on Base | | symbol | string | Yes | Token ticker symbol (1-20 chars) | | decimals | integer | Yes | Token decimal precision (0-77) | | logoUrl | string | null | No | Token logo URL |

reward

Discriminated union on type:

pool_split -- total amount split among all participants:

| Field | Type | Required | Description | |-------|------|----------|-------------| | type | "pool_split" | Yes | Reward type | | totalAmount | string | Yes | Total token amount to distribute (human-readable, e.g. "50000") |

fixed -- fixed amount per user:

| Field | Type | Required | Description | |-------|------|----------|-------------| | type | "fixed" | Yes | Reward type | | amountPerUser | string | Yes | Token amount per participant (e.g. "100") | | maxParticipants | integer | Yes | Maximum number of participants (must be positive) | | totalAmount | string | No | Optional override; defaults to amountPerUser * maxParticipants |

actions

| Field | Type | Default | Description | |-------|------|---------|-------------| | follow | boolean | true | Require follow | | like | boolean | false | Require like | | recast | boolean | false | Require recast | | quote | boolean | false | Require quote | | comment | boolean | false | Require comment | | prefilledQuoteMessage | string | null | null | Pre-filled message for quote casts (max 350 chars) |

targeting

| Field | Type | Default | Description | |-------|------|---------|-------------| | minFollowers | integer | 0 | Minimum Farcaster follower count | | minNeynarScore | number | 0 | Minimum Neynar user quality score (0.0-1.0) | | minQuotientScore | number | 0 | Minimum Quotient score | | requirePro | boolean | false | Require Farcaster Pro subscription | | requireVerifiedOnly | boolean | false | Exclude spam-labeled accounts | | requireProfilePhoto | boolean | false | Require a profile photo | | minAccountAgeDays | integer | 0 | Minimum account age in days | | minXFollowers | integer | 0 | Minimum X (Twitter) follower count (X campaigns) |

schedule

| Field | Type | Required | Description | |-------|------|----------|-------------| | endsAt | string | Yes | Campaign end date as ISO 8601 datetime (e.g. "2026-03-10T00:00:00.000Z") |

Commands

validate

Validate a campaign config file.

dropcast-cli validate --config <path> [--offline] [--json]

| Flag | Required | Description | |------|----------|-------------| | --config, -c | Yes | Path to campaign.json | | --offline | No | Schema validation only (no network calls) | | --json | No | Output as JSON |

create

Create a campaign. Dry-run by default; add --execute for live execution.

dropcast-cli create --config <path> [--execute] [--campaign-id <uuid>] [--yes] [--allow-fee-uncertain] [--json]

| Flag | Required | Description | |------|----------|-------------| | --config, -c | Yes | Path to campaign.json | | --execute | No | Send real transactions (requires PRIVATE_KEY) | | --campaign-id | No | Reuse a UUID for idempotent retries | | --yes, -y | No | Skip interactive confirmation prompt | | --allow-fee-uncertain | No | Proceed without quota surcharge when eligible count is unavailable | | --json | No | Output as JSON |

Without --execute, the command runs in dry-run mode: resolves on-chain data, calculates fees, checks balances, and prints a summary. No transactions are sent and PRIVATE_KEY is not required.

With --execute, the command:

1. Validates the config and runs pre-flight checks (chain ID, fee, balances, wallet match)
2. Approves ERC-20 token spend if needed
3. Calls fundCampaign() on the Router contract (sends tokens + ETH fee)
4. Writes a recovery file to .dropcast-cli/<campaignId>.json
5. Registers the campaign via POST /api/campaigns (with automatic 202 retry)
6. On success, deletes the recovery file and prints campaign details

All API requests include the X-Dropcast-Client: cli header, which the backend uses to tag campaigns as created_via='cli'. This enables deterministic filtering of CLI-originated campaigns (e.g. the /ai page). Historical campaigns created before this tagging was deployed may have created_via = NULL.

resume

Resume a funded-but-unregistered campaign from its recovery file. Sends no on-chain transactions.

dropcast-cli resume --recovery <path> [--json]

| Flag | Required | Description | |------|----------|-------------| | --recovery, -r | Yes | Path to recovery file (.dropcast-cli/<id>.json) | | --json | No | Output as JSON |

status

Show details for a single campaign.

dropcast-cli status --id <uuid|campaign_number> [--json]

| Flag | Required | Description | |------|----------|-------------| | --id | Yes | Campaign UUID or campaign number | | --json | No | Output as JSON |

list

List campaigns with pagination and status filter.

dropcast-cli list [--status active|ended|all] [--limit N] [--offset N] [--json]

| Flag | Required | Default | Description | |------|----------|---------|-------------| | --status | No | active | Filter: active, ended, or all | | --limit | No | 20 | Results per page | | --offset | No | 0 | Pagination offset | | --json | No | | Output as JSON |

Environment Variables

Set these in a .env file in the working directory or export them in your shell. See .env.example.

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | PRIVATE_KEY | For --execute only | -- | Hex private key of the funding wallet. Not needed for validate, status, list, or dry-run create | | DROPCAST_API_BASE_URL | No | https://dropcast.xyz | DropCast API base URL | | RPC_URL | No | https://mainnet.base.org | Base Mainnet RPC endpoint. Set this if you get RPC errors or rate limits | | DROPCAST_ROUTER_ADDRESS | No | 0xd216801c9B658f9bEcB8125387a2A02c0d7Cc3d2 | DropCast Router contract address |

Recovery / Resume Flow

If the CLI exits with an error after the on-chain funding transaction succeeds, tokens are already locked in the Router contract. A recovery file is automatically written to .dropcast-cli/<campaignId>.json.

Do NOT re-run create --execute -- this would send a second funding transaction and double-spend your tokens.

Instead, use the resume command to retry only the API registration:

# 1. Check the funding tx on BaseScan to confirm it succeeded

# 2. Resume API registration (no on-chain transaction)
dropcast-cli resume --recovery .dropcast-cli/<campaignId>.json

# 3. If resume succeeds, the recovery file is automatically deleted

# 4. If resume fails with 409, the campaign may already exist:
dropcast-cli status --id <campaignId>

The recovery file contains the campaign ID, funding transaction hash, fee paid, and the full config. Do not modify it.

Agent Skill

This package includes an AI agent skill definition at skill/SKILL.md. It provides structured instructions for AI agents to create DropCast campaigns programmatically. See the skill/ directory for the full skill definition, templates, and reference docs.

Troubleshooting

RPC errors or rate limits

The default RPC (https://mainnet.base.org) has rate limits. Set a custom RPC endpoint:

# In .env
RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY

Wallet mismatch

Wallet mismatch: PRIVATE_KEY wallet 0xAAA... != config host.walletAddress 0xBBB...

The wallet derived from PRIVATE_KEY must match host.walletAddress in your config. The backend rejects registration (403) if they differ.

Insufficient balance

Insufficient ETH. Need ~0.0026 (fee + gas), have 0.0010.

The wallet needs enough ETH for the platform fee plus a 0.001 ETH gas buffer, and enough of the airdrop token to cover totalAmount.

Fee mismatch

Fee mismatch: local fee 0.0016 ETH < on-chain minBaseFee 0.0020 ETH

The bundled fee schedule may be stale. Update the CLI to the latest version: npm update -g dropcast-cli.

Post-funding API failure

If the campaign was funded on-chain but API registration failed:

1. Do NOT re-run create --execute (would double-spend)
2. Use resume with the recovery file (see Recovery / Resume Flow)
3. If resume fails with 409, check status --id <campaignId> -- the campaign may already exist

202 pending finality

The CLI retries 202 responses automatically with exponential backoff (up to ~2 minutes). If retries are exhausted, use resume with the recovery file or check status --id <campaignId>.

License

MIT