Neynar Documentation

Managing Onchain Wallets - Wallet setup guide

Understanding Wallet ID for Fungible Transfers

This endpoint allows you to send fungible tokens (ERC-20, SPL tokens, etc.) in bulk to multiple Farcaster users. You can send tokens using their FID (Farcaster ID) instead of wallet addresses.

Wallet ID (REQUIRED)

The x-wallet-id header is REQUIRED for this endpoint. You must provide a funded wallet that will execute the token transfers on your behalf.

New to Wallet IDs? See Managing Onchain Wallets to create your app wallet in the developer portal and obtain your x-wallet-id value.

Code Examples

Basic Token Transfer

const response = await fetch('https://api.neynar.com/v2/farcaster/fungible/send', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_NEYNAR_API_KEY',
    'x-wallet-id': 'your-wallet-id',  // REQUIRED
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    token_address: '0x...',  // ERC-20 contract address
    network: 'base',
    recipients: [
      { fid: 12345, amount: '1.5' },
      { fid: 67890, amount: '2.0' }
    ]
  })
});

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

Supported Networks

You can send fungibles on:

Network	Token Standard	Native Token
Base	ERC-20	ETH
Optimism	ERC-20	ETH
Base Sepolia	ERC-20 (testnet)	ETH
Solana	SPL	SOL

What You’re Paying For

When you send fungibles with a wallet_id:

Services Included:
- FID to wallet address resolution
- Transaction execution and monitoring
- Gas estimation and optimization
- Retry logic for failed transactions
- Batch processing support

Batch Transfers

Send to multiple recipients in a single API call:

const recipients = [
  { fid: 12345, amount: '1.0' },
  { fid: 23456, amount: '2.5' },
  { fid: 34567, amount: '0.5' },
  { fid: 45678, amount: '1.5' }
];

const response = await fetch('https://api.neynar.com/v2/farcaster/fungible/send', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_NEYNAR_API_KEY',
    'x-wallet-id': 'your-wallet-id',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    token_address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
    network: 'base',
    recipients: recipients
  })
});

const result = await response.json();
console.log(`Sent to ${result.transactions.length} recipients`);

Batch Processing: The API processes transfers in parallel for better efficiency. Each recipient gets their own transaction.

Error Handling

Error: Missing Wallet ID

{
  "code": "RequiredField",
  "message": "x-wallet-id header is required"
}

Solution: Add the x-wallet-id header. See Managing Onchain Wallets for setup.

Error: Invalid Wallet ID

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

Solution: Verify your wallet_id in the Developer Portal or contact support.

Error: Insufficient Wallet Balance

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

Solution: Fund your wallet with more tokens (and gas tokens) on the target network.

Error: Insufficient Token Balance

{
  "code": "InsufficientTokenBalance",
  "message": "Wallet does not have enough of the specified token to complete transfers."
}

Solution: Ensure your wallet has enough of the token you’re trying to send, plus gas tokens for fees.

Use Cases

Reward Community Members

// Reward top contributors with USDC
const topContributors = [
  { fid: 12345, amount: '100' },  // $100 USDC
  { fid: 23456, amount: '50' },   // $50 USDC
  { fid: 34567, amount: '25' }    // $25 USDC
];

await sendFungibles({
  token_address: USDC_ADDRESS,
  network: 'base',
  recipients: topContributors
});

Airdrop Custom Tokens

// Airdrop your custom token to holders
const airdropList = users.map(user => ({
  fid: user.fid,
  amount: calculateAirdropAmount(user)
}));

await sendFungibles({
  token_address: YOUR_TOKEN_ADDRESS,
  network: 'base',
  recipients: airdropList
});

Pay for Services

// Pay creators for their work
await sendFungibles({
  token_address: USDC_ADDRESS,
  network: 'base',
  recipients: [
    { fid: artistFid, amount: paymentAmount }
  ]
});

Node.js SDK

🔗 SDK Method: sendFungiblesToUsers Use the Neynar Node.js SDK for typed responses and better developer experience:

import { NeynarAPIClient } from "@neynar/nodejs-sdk";

const client = new NeynarAPIClient({ apiKey: "YOUR_API_KEY" });

const result = await client.sendFungiblesToUsers({
  walletId: "your-wallet-id",
  tokenAddress: "0x...",
  network: "base",
  recipients: [
    { fid: 12345, amount: "1.0" }
  ]
});

Best Practices

Security

✅ Validate recipients - Verify FIDs before sending
✅ Set reasonable limits - Implement transfer caps
✅ Monitor transactions - Track all transfers
✅ Handle errors gracefully - Implement retry logic

Operations

✅ Fund wallet adequately - Ensure sufficient token and gas balance
✅ Batch when possible - More efficient for multiple recipients
✅ Test on testnet first - Use Base Sepolia before mainnet
✅ Monitor wallet balance - Set up low balance alerts

Cost Optimization

✅ Batch transfers - Reduce per-recipient costs
✅ Choose right network - Base often has lower gas costs than Optimism
✅ Monitor gas prices - Send during low-traffic periods when possible
✅ Use efficient tokens - Some ERC-20s are more gas-efficient than others

Next Steps

Manage Your Wallet

Set up and fund your wallet for token transfers

Fetch User Balance

Check token balances for Farcaster users

Mint NFTs

Mint NFTs to Farcaster users

Contact Support

Need help? Reach out to our team

Authorizations

x-api-key

string

header

default:NEYNAR_API_DOCS

required

API key to authorize requests

Headers

x-wallet-id

string

required

Wallet ID to use for transactions

Body

application/json

network

enum<string>

required

Available options:

base,

optimism,

base-sepolia

recipients

TransactionSendFungiblesRecipient · object[]

required

Required array length: 1 - 200 elements

Show child attributes

fungible_contract_address

string

Contract address of the fungible token to send. If not provided, the default is the native token of the network.

Example:

"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"

Response

Success

send_receipts

TransactionSendFungiblesReceipt · object[]

required

Show child attributes

transactions

TransactionSendTxInfo · object[]

required

Show child attributes

Overview

Farcaster

Deploy onchain

Farcaster Hub API

Other SDKs

Github

Send fungibles

Understanding Wallet ID for Fungible Transfers

Wallet ID (REQUIRED)

Code Examples

Basic Token Transfer

Supported Networks

What You’re Paying For

Batch Transfers

Error Handling

Error: Missing Wallet ID

Error: Invalid Wallet ID

Error: Insufficient Wallet Balance

Error: Insufficient Token Balance

Use Cases

Reward Community Members

Airdrop Custom Tokens

Pay for Services

Node.js SDK

Best Practices

Security

Operations

Cost Optimization

Next Steps

Manage Your Wallet

Fetch User Balance

Mint NFTs

Contact Support

Authorizations

Headers

Body

Response

Overview

Farcaster

Deploy onchain

Farcaster Hub API

Other SDKs

Github

​Related documentation:

​Understanding Wallet ID for Fungible Transfers

​Wallet ID (REQUIRED)

​Code Examples

​Basic Token Transfer

​Supported Networks

​What You’re Paying For

​Batch Transfers

​Error Handling

​Error: Missing Wallet ID

​Error: Invalid Wallet ID

​Error: Insufficient Wallet Balance

​Error: Insufficient Token Balance

​Use Cases

​Reward Community Members

​Airdrop Custom Tokens

​Pay for Services

​Node.js SDK

​Best Practices

​Security

​Operations

​Cost Optimization

​Next Steps

Manage Your Wallet

Fetch User Balance

Mint NFTs

Contact Support

Authorizations

Headers

Body

Response

Related documentation:

Understanding Wallet ID for Fungible Transfers

Wallet ID (REQUIRED)

Code Examples

Basic Token Transfer

Supported Networks

What You’re Paying For

Batch Transfers

Error Handling

Error: Missing Wallet ID

Error: Invalid Wallet ID

Error: Insufficient Wallet Balance

Error: Insufficient Token Balance

Use Cases

Reward Community Members

Airdrop Custom Tokens

Pay for Services

Node.js SDK

Best Practices

Security

Operations

Cost Optimization

Next Steps