{"platform":"ChainCraft","version":"2.0.0","authentication":{"header":"X-API-Key","format":"X-API-Key: cc_live_<your-key>","obtain":"Register at /dashboard/register/, then Dashboard → Settings → API Keys.","note":"Only POST /api/v1/faucet/drip is public. All other endpoints require the header."},"quickstart":[{"step":1,"description":"Create a managed wallet","method":"POST","path":"/api/v1/wallets/create","body":"{}","note":"Returns address + mnemonic. Save the mnemonic — shown only once."},{"step":2,"description":"Fund the wallet from the public faucet (no API key needed)","method":"POST","path":"/api/v1/faucet/drip","body":"{\"address\": \"<wallet-address>\", \"amount_ether\": 1.0}","note":"Rate-limited. Field name is 'address', not 'to' or 'wallet_address'."},{"step":3,"description":"Check wallet ETH balance","method":"GET","path":"/api/v1/wallets/{address}/balance","body":null,"note":"Returns balance_wei and balance_ether."},{"step":4,"description":"Create an NFT collection","method":"POST","path":"/api/v1/tokens/nft/collections/create","body":"{\"name\": \"My Collection\", \"symbol\": \"MYC\", \"collection_type\": \"erc721\", \"owner_address\": \"<wallet-address>\"}","note":"collection_type accepts: erc721, erc1155, soulbound (case-insensitive)."},{"step":5,"description":"Mint an NFT to an address","method":"POST","path":"/api/v1/tokens/nft/mint","body":"{\"collection_id\": \"<id-from-step-4>\", \"to_address\": \"<recipient-address>\", \"metadata_uri\": \"ipfs://...\", \"sender_address\": \"<wallet-address>\"}","note":"sender_address must own or be authorised on the collection."}],"modules":[{"name":"wallets","description":"HD wallet generation, ETH management, message signing.","endpoints":[{"method":"POST","path":"/api/v1/wallets/create","auth":true,"description":"Generate new HD wallet. Returns address + mnemonic (once)."},{"method":"POST","path":"/api/v1/wallets/import","auth":true,"description":"Import via private_key or mnemonic."},{"method":"GET","path":"/api/v1/wallets/{address}/balance","auth":true,"description":"ETH balance in wei and ether."},{"method":"POST","path":"/api/v1/wallets/{address}/fund","auth":true,"description":"Fund project-owned wallet from faucet. Body: {amount_ether}."},{"method":"POST","path":"/api/v1/wallets/{address}/send","auth":true,"description":"Send ETH. Body: {to_address, amount_ether}."},{"method":"POST","path":"/api/v1/wallets/{address}/sign","auth":true,"description":"Sign a message. Body: {message}."},{"method":"GET","path":"/api/v1/wallets/{address}/transactions","auth":true,"description":"Transaction history."},{"method":"POST","path":"/api/v1/faucet/drip","auth":false,"description":"Public faucet. Body: {address, amount_ether}. No API key needed."}]},{"name":"chain","description":"Block explorer, transaction lookup, gas info. Read-only. Private blockchain (not Ethereum mainnet).","endpoints":[{"method":"GET","path":"/api/v1/chain/info","auth":true,"description":"Chain ID, block height, network name."},{"method":"GET","path":"/api/v1/chain/block/latest","auth":true,"description":"Latest block."},{"method":"GET","path":"/api/v1/chain/block/{n}","auth":true,"description":"Block by number."},{"method":"GET","path":"/api/v1/chain/tx/{hash}","auth":true,"description":"Transaction details."},{"method":"GET","path":"/api/v1/chain/gas","auth":true,"description":"Current gas price."},{"method":"GET","path":"/api/v1/chain/search","auth":true,"description":"Search by address, tx hash, or block. Query param: q."}]},{"name":"contracts","description":"Deploy from templates, call read functions, send write transactions.","endpoints":[{"method":"GET","path":"/api/v1/contracts/templates","auth":true,"description":"List available contract templates."},{"method":"POST","path":"/api/v1/contracts/deploy-template","auth":true,"description":"Deploy a template. Body: {template_id, deployer_address, constructor_args}."},{"method":"POST","path":"/api/v1/contracts/{address}/call","auth":true,"description":"Call read-only function. Body: {function_name, args, abi}."},{"method":"POST","path":"/api/v1/contracts/{address}/send","auth":true,"description":"Send write transaction. Body: {function_name, args, sender_address, abi}."},{"method":"GET","path":"/api/v1/contracts/{address}/abi","auth":true,"description":"Retrieve stored ABI."},{"method":"GET","path":"/api/v1/contracts/{address}/events","auth":true,"description":"Recent contract events."}]},{"name":"tokens","description":"ERC-721, ERC-1155, Soulbound NFTs and ERC-20 fungible tokens.","endpoints":[{"method":"POST","path":"/api/v1/tokens/nft/collections/create","auth":true,"description":"Deploy NFT collection. collection_type: erc721 | erc1155 | soulbound (case-insensitive)."},{"method":"POST","path":"/api/v1/tokens/nft/mint","auth":true,"description":"Mint one NFT. Body: {collection_id, to_address, metadata_uri, sender_address}."},{"method":"POST","path":"/api/v1/tokens/nft/mint-batch","auth":true,"description":"Mint to multiple recipients in one tx."},{"method":"POST","path":"/api/v1/tokens/nft/{collection_id}/{token_id}/transfer","auth":true,"description":"Transfer NFT."},{"method":"POST","path":"/api/v1/tokens/fungible/create","auth":true,"description":"Deploy ERC-20. Body: {name, symbol, decimals, initial_supply, owner_address}."},{"method":"POST","path":"/api/v1/tokens/fungible/{id}/mint","auth":true,"description":"Mint tokens. Body: {to_address, amount, sender_address}."}]},{"name":"storage","description":"IPFS upload and pinning.","endpoints":[{"method":"POST","path":"/api/v1/storage/upload/json","auth":true,"description":"Upload JSON object to IPFS. Returns CID."},{"method":"POST","path":"/api/v1/storage/upload/file","auth":true,"description":"Upload file (multipart). Returns CID."},{"method":"GET","path":"/api/v1/storage/fetch/{cid}","auth":true,"description":"Retrieve content by CID."},{"method":"POST","path":"/api/v1/storage/pin/{cid}","auth":true,"description":"Pin a CID to keep it available."},{"method":"GET","path":"/api/v1/storage/stats","auth":true,"description":"IPFS node stats."}]},{"name":"crypto","description":"Hashing, signing, symmetric/asymmetric encryption, Merkle trees, Shamir secret sharing.","endpoints":[{"method":"POST","path":"/api/v1/crypto/hash","auth":true,"description":"Hash data. Body: {data, algorithm}. Algorithms: sha256, keccak256, sha3."},{"method":"POST","path":"/api/v1/crypto/sign","auth":true,"description":"Sign message with wallet. Body: {message, signer_address}."},{"method":"POST","path":"/api/v1/crypto/verify-signature","auth":true,"description":"Recover signer from signature."},{"method":"POST","path":"/api/v1/crypto/encrypt","auth":true,"description":"Symmetric AES-256 encryption."},{"method":"POST","path":"/api/v1/crypto/merkle/create","auth":true,"description":"Build Merkle tree from list of leaves."},{"method":"POST","path":"/api/v1/crypto/shamir/split","auth":true,"description":"Split secret into n shares (k-of-n threshold)."}]},{"name":"verify","description":"On-chain proof verification.","endpoints":[{"method":"POST","path":"/api/v1/verify/document","auth":true,"description":"Verify a document hash against oracle timestamp proof."},{"method":"POST","path":"/api/v1/verify/token","auth":true,"description":"Verify NFT ownership and validity."},{"method":"POST","path":"/api/v1/verify/ownership","auth":true,"description":"Verify wallet owns a token."},{"method":"GET","path":"/api/v1/verify/qr/{contract}/{token_id}","auth":true,"description":"Generate QR code for token verification."}]},{"name":"oracle","description":"On-chain data feeds and document timestamping.","endpoints":[{"method":"POST","path":"/api/v1/oracle/timestamp","auth":true,"description":"Anchor document hash on-chain. Body: {document_hash, sender_address}. IMPORTANT: field is 'document_hash' (not 'hash')."},{"method":"POST","path":"/api/v1/oracle/feeds/create","auth":true,"description":"Deploy on-chain data feed oracle."},{"method":"POST","path":"/api/v1/oracle/feeds/{id}/push","auth":true,"description":"Push value to feed. Body: {value, sender_address}."},{"method":"GET","path":"/api/v1/oracle/feeds/{id}/latest","auth":true,"description":"Latest value from feed."}]},{"name":"governance","description":"DAO governance contracts with on-chain voting.","endpoints":[{"method":"POST","path":"/api/v1/governance/create","auth":true,"description":"Deploy governance contract. governance_type: 'simple' (no token needed) or 'governor' (token-weighted). IMPORTANT: only these two values are valid."},{"method":"POST","path":"/api/v1/governance/{id}/propose","auth":true,"description":"Create a proposal. Body: {title, description, proposer_address}."},{"method":"POST","path":"/api/v1/governance/{id}/vote","auth":true,"description":"Cast vote. Body: {proposal_id, voter_address, support}. support: for|against|abstain."},{"method":"POST","path":"/api/v1/governance/{id}/execute/{pid}","auth":true,"description":"Execute a passed proposal."}]}],"common_mistakes":[{"mistake":"Using 'Authorization: Bearer cc_live_...' header","correct":"Use 'X-API-Key: cc_live_...' header","detail":"ChainCraft uses a custom X-API-Key header, not OAuth Bearer tokens."},{"mistake":"POST /api/v1/wallets/faucet or /api/v1/faucet","correct":"POST /api/v1/faucet/drip","detail":"Public faucet is at /faucet/drip. Body field is 'address' (not 'to' or 'wallet_address')."},{"mistake":"governance_type: 'basic' or 'token' or 'dao'","correct":"governance_type: 'simple' or 'governor'","detail":"Only two values accepted. 'simple' needs no token. 'governor' requires voting_token_address."},{"mistake":"oracle body: {\"hash\": \"0x...\", \"metadata\": {...}}","correct":"oracle body: {\"document_hash\": \"0x...\", \"sender_address\": \"0x...\"}","detail":"Field is 'document_hash' not 'hash'. 'sender_address' is required, 'metadata' is not a field."},{"mistake":"Trying to control wallets from another project","correct":"Only wallets created under your API key's project can be controlled","detail":"403 is returned when addressing wallets not owned by the requesting project."},{"mistake":"Assuming this is Ethereum mainnet or a testnet","correct":"ChainCraft runs a private blockchain","detail":"Block 1 was mined 2026-03-02. Use the faucet for test ETH — mainnet ETH is irrelevant."}]}