Managing Onchain Wallets

​

What is a Wallet ID?

​

When Do You Need a Wallet ID?

​

Getting Your Wallet Set Up

​

Setup Process

1. Go to the Neynar Developer Portal
2. Select your app from the dashboard
3. Navigate to the “App Wallet” tab in your app settings
4. Copy your wallet_id - You’ll see a field displaying your wallet ID once created
5. Copy your wallet address(es) - You’ll receive wallet addresses for each supported network
6. Fund your wallet with gas tokens (see below)
7. Start using the wallet_id in your API calls immediately!

​

What You’ll Get

1. Wallet ID - A unique identifier to use in API headers (e.g., wlt_abc123...)
2. Wallet Addresses - Ethereum addresses for each network where you can send gas tokens (e.g., 0x1234...)

​

Finding Your Wallet ID

1. Go to dev.neynar.com
2. Select your app
3. Navigate to the “App Wallet” tab
4. Copy your wallet_id value

​

Funding Your Wallet

​

Supported Networks

​

How to Fund

1. Get your wallet address from setup email or portal
2. Send gas tokens to that address using any wallet (MetaMask, Coinbase Wallet, etc.)
3. Recommended amounts:
   • Testing: 0.01 ETH
   • Low volume (<100 ops/day): 0.1 ETH
   • High volume (>1000 ops/day): 1+ ETH

​

Funding Example

# Using MetaMask or any wallet:
# 1. Switch to the appropriate network (Base, Optimism, etc.)
# 2. Send ETH to your wallet address
# 3. Wait for confirmation

# Example wallet address (yours will be different):
# 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

​

Monitoring Balance

​

Check Balance Manually

https://basescan.org/address/YOUR_WALLET_ADDRESS

https://optimistic.etherscan.io/address/YOUR_WALLET_ADDRESS

https://sepolia.basescan.org/address/YOUR_WALLET_ADDRESS

​

Developer Portal

• Current balance per network
• Recent transactions
• Wallet addresses for each network
• Transaction history

​

Using Your Wallet ID

​

Example: Minting NFTs

const response = await fetch('https://api.neynar.com/v2/farcaster/nft/mint', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_NEYNAR_API_KEY',
    'x-wallet-id': 'your-wallet-id',  // ← Your wallet ID here
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    nft_contract_address: '0x...',
    network: 'base',
    recipients: [{ fid: 12345, quantity: 1 }]
  })
});

const result = await response.json();
console.log('Minted:', result);

​

Example: Buying Storage

const response = await fetch('https://api.neynar.com/v2/farcaster/storage/buy', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_NEYNAR_API_KEY',
    'x-wallet-id': 'your-wallet-id',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fid: 12345,
    units: 1
  })
});

​

Error Handling

​

Missing Wallet ID

{
  "code": "Unauthorized",
  "message": "Your app is not authorized for this operation. Please provide x-wallet-id header or contact support for allowlist access."
}

​

Invalid Wallet ID

{
  "code": "InvalidWalletId",
  "message": "The provided wallet_id is invalid or not found."
}

​

Insufficient Balance

{
  "code": "InsufficientFunds",
  "message": "Wallet does not have enough balance to complete this transaction."
}

​

Best Practices

​

Security

• ✅ Store wallet_id securely - Treat it like an API key
• ✅ Use environment variables - Never commit wallet_id to code
• ✅ Rotate if compromised - Contact support for new wallet_id
• ❌ Don’t share publicly - Keep wallet_id private

​

Operations

• ✅ Monitor balance regularly - Set up alerts for low balance
• ✅ Fund adequately - Ensure sufficient gas for your volume
• ✅ Test on testnet first - Use Base Sepolia before mainnet
• ✅ Handle errors gracefully - Implement retry logic

​

Cost Optimization

• ✅ Batch operations when possible
• ✅ Monitor gas prices - Some operations can wait for lower gas
• ✅ Choose right network - Base often has lower gas costs than Optimism, some transactions can only be done on certain networks.

​

FAQ

​

Can I use one wallet_id for multiple apps?

​

What happens if my wallet runs out of funds?

​

Can I withdraw funds from my wallet?

​

Can I see transaction history?

​

Related Documentation

​

Need Help?