Skip to main content
Airdrops distribute BCH or CashTokens to many recipients at once. Open airdrops let anyone claim. KYC-restricted airdrops use a merkle tree to whitelist specific addresses.

​
List Campaigns (Creator)

GET /api/airdrops?creator={address}
Returns all campaigns created by the given address.

​
List Claimable Campaigns

GET /api/airdrops/claimable?address={address}
Returns all ACTIVE campaigns the given address has not yet claimed (or has remaining claims on). 
GET /api/airdrops/claim/:token
Resolves a claim link token (from the campaign’s claim_link URL) to the full campaign record.

​
Get Campaign

GET /api/airdrops/:id
Returns the campaign record and its full claim history.

​
Create Campaign

POST /api/airdrops/create
Deploys the AirdropCovenant on-chain and stores status: PENDING. Body 
{
  "creator": "bchtest:qr...",
  "title": "Community Rewards Q1",
  "campaignType": "AIRDROP",
  "tokenType": "BCH",
  "totalAmount": 100,
  "amountPerClaim": 0.5,
  "startDate": 1700000000,
  "endDate": 1731536000,
  "maxClaimsPerAddress": 1,
  "requireKyc": false,
  "vaultId": "optional-vault-uuid"
}
For token airdrops add "tokenType": "FUNGIBLE_TOKEN" and "tokenCategory": "hex32". Response 
{
  "success": true,
  "campaign": { "id": "...", "status": "PENDING", "claim_link": "https://..." },
  "deployment": {
    "contractAddress": "bchtest:p...",
    "fundingRequired": true,
    "nftCommitment": "hex..."
  }
}

​
Generate Merkle Tree

POST /api/airdrops/:id/generate-merkle
For KYC-restricted campaigns. Build a merkle tree from an explicit recipient list before funding. Body 
{
  "recipients": [
    { "address": "bchtest:qr...", "amount": 1.0 },
    { "address": "bchtest:qs...", "amount": 0.5 }
  ]
}
Response 
{
  "success": true,
  "merkleRoot": "hex32",
  "totalRecipients": 2,
  "leaves": [...]
}

​
Get Funding Info

GET /api/airdrops/:id/funding-info
Returns the unsigned wcTransaction to fund the campaign contract. KYC campaigns must generate their merkle tree first.

​
Confirm Funding

POST /api/airdrops/:id/confirm-funding

{ "txHash": "hex64" }
Verifies the contract output on-chain and transitions the campaign to ACTIVE.

​
Get Merkle Proof

GET /api/airdrops/:id/proof/:address
Returns the merkle proof for an address. Public campaigns return "publicCampaign": true with an empty proof array.

​
Claim

POST /api/airdrops/:id/claim

{ "claimerAddress": "bchtest:q..." }
Builds the claim wcTransaction. For KYC campaigns, verifies the claimer is in the merkle tree. Enforces maxClaimsPerAddress.

​
Confirm Claim

POST /api/airdrops/:id/confirm-claim

{
  "claimerAddress": "bchtest:q...",
  "claimedAmount": 0.5,
  "txHash": "hex64"
}
Records the claim and increments claimed_count.

​
Pause / Resume / Cancel

POST /api/airdrops/:id/pause
POST /api/airdrops/:id/resume
POST /api/airdrops/:id/cancel
x-user-address: bchtest:q...
Creator-only. Each returns an unsigned wcTransaction. Follow with the matching confirm-pause, confirm-resume, or confirm-cancel endpoint.