MoltPunks API Documentation

Version: 1.0.0 | Base URL: https://api.moltpunks.xyz

Overview

MoltPunks is a collection of 10,000 unique digital collectibles on the Base blockchain. This API is designed with an agent-first approach - all endpoints return JSON for easy programmatic access. There are NO browser-based wallet connection libraries. AI agents and scripts interact directly with the blockchain using standard signing methods via private keys or hardware wallets.

Production Ready

This API uses real snapshot-based Merkle proofs generated from eligible MBC-20 holder addresses. Proofs are verified on-chain against the Merkle root stored in the MoltPunks contract.

Eligibility: Check your address eligibility by calling GET /api/proofs/:address. Only addresses with valid Merkle proofs can claim tokens.

Complete Claim Flow

Follow these numbered steps to claim a MoltPunk NFT:

1 Discover Collection Metadata

curl https://api.moltpunks.xyz/collection.json

Returns collection details including contract address, chain ID, claim fee, and example workflows.

2 Check Eligibility

curl https://api.moltpunks.xyz/api/proofs/0xYourAddress

Returns Merkle proofs for all tokens your address is eligible to claim. Returns 404 if not eligible.

3 Generate Unsigned Transaction

curl -X POST https://api.moltpunks.xyz/api/claim \
  -H "Content-Type: application/json" \
  -d '{"wallet":"0xYourAddress","tokenId":42}'

Returns an unsigned transaction with encoded calldata, value, and gas limit.

4 Sign Transaction

Sign the transaction using one of these methods:

Using cast (Foundry)

cast send 0x7e390734E50ac3B0a957Bc8DE8759e0Ef5eC1b92 \
  --value 0.005ether \
  --rpc-url https://mainnet.base.org \
  --private-key YOUR_PRIVATE_KEY \
  --data CALLDATA_FROM_STEP_3

Using ethers.js (v6)

import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);

const tx = await wallet.sendTransaction({
  to: '0x7e390734E50ac3B0a957Bc8DE8759e0Ef5eC1b92',
  data: CALLDATA_FROM_STEP_3,
  value: ethers.parseEther('0.005'),
  chainId: 8453
});

await tx.wait();

Using viem

import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const account = privateKeyToAccount(PRIVATE_KEY);
const client = createWalletClient({
  account,
  chain: base,
  transport: http()
});

const hash = await client.sendTransaction({
  to: '0x7e390734E50ac3B0a957Bc8DE8759e0Ef5eC1b92',
  data: CALLDATA_FROM_STEP_3,
  value: 5000000000000000n, // 0.005 ETH in wei
});

await client.waitForTransactionReceipt({ hash });

5 Broadcast to Network

curl -X POST https://mainnet.base.org \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["SIGNED_TX_HEX"],"id":1}'

Submits the signed transaction to the Base network.

6 Verify Claim

curl https://api.moltpunks.xyz/api/punk/42

Check the metadata to confirm properties.claimed is true and properties.owner is your address.

Important: Agent-First Design

This API does NOT use browser-based wallet connection libraries. Those tools are designed for interactive browser wallets, not programmatic access. AI agents should sign transactions directly using private keys or hardware wallets via the methods shown above.

API Endpoints

GET/collection.json

Returns collection metadata including contract address, chain details, and claim instructions.

Response Schema

{
  "name": "MoltPunks",
  "description": "...",
  "contractAddress": "0x...",
  "chain": "base",
  "chainId": 8453,
  "totalSupply": 10000,
  "claimFee": "0.005",
  "rpcUrl": "https://mainnet.base.org",
  "apiBaseUrl": "https://api.moltpunks.xyz",
  "claimInstructions": "..."
}

GET/api/proofs/:address

Fetches Merkle proofs for all tokens claimable by the given address.

Parameters

address - Ethereum address (checksummed or lowercase)

Response Schema

{
  "wallet": "0xCheckSummedAddress",
  "proofs": [
    {
      "tokenId": 42,
      "proof": ["0xhash1", "0xhash2", ...]
    }
  ]
}

Errors

400 - Invalid address format
404 - Address not eligible (no proofs found)
429 - Rate limit exceeded (100 req/min)

POST/api/claim

Generates an unsigned transaction for claiming a single token.

Request Schema

{
  "wallet": "0xYourAddress",
  "tokenId": 42
}

Response Schema

{
  "transaction": {
    "to": "0xContractAddress",
    "data": "0x...",
    "value": "5000000000000000",
    "chainId": 8453,
    "gasLimit": 150000
  },
  "signing": {
    "instructions": "...",
    "rpcUrl": "https://mainnet.base.org",
    "method": "eth_sendTransaction",
    "exampleCast": "...",
    "exampleEthers": "..."
  },
  "punk": {
    "tokenId": 42,
    "metadata": {...}
  }
}

Errors

400 - Invalid wallet or tokenId
404 - No proof found for this wallet/tokenId combination
429 - Rate limit exceeded (100 req/min)

GET/api/punk/:id

Returns ERC-721 compliant metadata for a specific punk, merged with on-chain claim status.

Response Schema

{
  "name": "MoltPunk #42",
  "description": "...",
  "image": "https://images.moltpunks.xyz/punks/42.png",
  "external_url": "https://moltpunks.xyz",
  "attributes": [
    {"trait_type": "Type", "value": "Female"},
    {"trait_type": "Accessory", "value": "Wild Hair"}
  ],
  "properties": {
    "original_cryptopunk": 42,
    "claimed": true,
    "owner": "0x...",
    "claim_tx": null
  }
}

GET/api/stats

Returns collection-wide statistics.

Response Schema

{
  "totalSupply": 10000,
  "totalClaimed": 150,
  "uniqueHolders": 85,
  "claimRate": 0.015
}

Cached for 5 minutes.

GET/api/gallery

Returns paginated gallery of punks with filtering support.

Query Parameters

page - Page number (default: 1)
limit - Items per page (default: 100, max: 1000)
claimed - Filter by claim status (true/false)
trait - Filter by trait value (e.g., "Male", "Female")

Response Schema

{
  "punks": [...],
  "page": 1,
  "limit": 100,
  "total": 10000
}

Rate Limits

Endpoint	Limit	Window
All endpoints	100 requests	Per minute per IP

When rate limited, API returns 429 Too Many Requests with retry instructions.

Error Codes

Code	Message	Resolution
400	Invalid request	Check request body format and parameter types
404	Resource not found	Verify token ID range (0-9999) or address eligibility
429	Rate limit exceeded	Wait 60 seconds before retrying
500	Internal server error	Retry request or contact support

Troubleshooting

Transaction Fails with "Insufficient funds"

Ensure your wallet has at least 0.005 ETH plus gas fees (approximately 0.006 ETH total recommended).

Transaction Fails with "Invalid proof"

Verify that you're using the correct wallet address from step 2. Proofs are wallet-specific and cannot be transferred.

Getting 404 on /api/proofs/:address

Your address is not in the eligibility list. Eligibility is determined by the MBC-20 snapshot taken at block height specified in the contract. Only addresses that held MBC-20 tokens at snapshot time can claim MoltPunks.

Rate Limited (429 Error)

You've exceeded 100 requests per minute. Wait 60 seconds before making additional requests.

Gas Estimation Issues

Use the gasLimit provided in the /api/claim response. Claims use 150,000 gas limit.

CORS Configuration

All endpoints support CORS with Access-Control-Allow-Origin: * for easy integration from any origin. The claim endpoint (/api/claim) restricts origin to https://moltpunks.xyz for security.

Support

For additional help:

Check contract on BaseScan
View collection at moltpunks.xyz
API health check: /health

Last updated: 2026-02-09 | API Version: 1.0.0