> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neynar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Onchain Wallets

> Set up and manage your wallet for onchain Farcaster operations

## What is a Wallet ID?

A `wallet_id` is a unique identifier for an app wallet that Neynar operates on your behalf. When you use a wallet\_id, Neynar executes onchain transactions for you, handling gas estimation, transaction submission, and retry logic automatically.

Think of it as a server-side wallet that you fund with gas tokens, and Neynar manages the technical complexity of blockchain interactions.

## When Do You Need a Wallet ID?

You need a `wallet_id` for all onchain operations on Neynar:

| Operation            | Endpoint                           | Wallet ID Status |
| -------------------- | ---------------------------------- | ---------------- |
| **Mint NFTs**        | `POST /v2/farcaster/nft/mint`      | **REQUIRED**     |
| **Send Fungibles**   | `POST /v2/farcaster/fungible/send` | **REQUIRED**     |
| **Buy Storage**      | `POST /v2/farcaster/storage/buy`   | **REQUIRED**     |
| **Fetch FID**        | `GET /v2/farcaster/user/fid`       | **REQUIRED**     |
| **Register Account** | `POST /v2/farcaster/user/`         | **REQUIRED**     |

<Info>
  **All onchain operations require a wallet\_id.** This ensures consistent billing and gives you full control over your onchain spending.
</Info>

***

## Getting Your Wallet Set Up

App wallets are **self-service** - you can create them directly in the developer portal!

### Setup Process

1. **Go to the [Neynar Developer Portal](https://dev.neynar.com)**

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!

<Note>
  **Need Help?** If you encounter any issues during setup, message our [developer Slack](https://neynar.com/slack).
</Note>

### What You'll Get

When you create an app wallet, you'll receive:

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

Your wallet\_id is available anytime in the developer portal:

1. Go to [dev.neynar.com](https://dev.neynar.com)
2. Select your app
3. Navigate to the "App Wallet" tab
4. Copy your `wallet_id` value

**Keep this information secure** - treat your wallet\_id like an API key.

## Funding Your Wallet

Your wallet needs native gas tokens on the networks where you'll operate:

### Supported Networks

| Network          | Gas Token     | Use Case                                   |
| ---------------- | ------------- | ------------------------------------------ |
| **Base**         | ETH           | Production NFT minting, mainnet operations |
| **Optimism**     | ETH           | Account registration, storage purchases    |
| **Base Sepolia** | ETH (testnet) | Testing and development                    |

### 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

```bash theme={"system"}
# 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
```

<Tip>
  **Gas Costs:** Typical operations cost:

  * NFT mint: \~\$0.01-0.05 in gas
  * Account registration: \~\$0.10-0.50 in gas
  * Storage purchase: \~\$0.05-0.20 in gas
</Tip>

## Monitoring Balance

### Check Balance Manually

You can view your wallet balance on any block explorer:

**Base:**

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

**Optimism:**

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

**Base Sepolia:**

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

### Developer Portal

The developer portal shows:

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

## Using Your Wallet ID

Add the `x-wallet-id` header to your API requests:

### Example: Minting NFTs

<CodeGroup>
  ```javascript Node.js theme={"system"}
  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);
  ```

  ```bash cURL theme={"system"}
  curl -X POST 'https://api.neynar.com/v2/farcaster/nft/mint' \
    -H 'x-api-key: YOUR_NEYNAR_API_KEY' \
    -H 'x-wallet-id: your-wallet-id' \
    -H 'Content-Type: application/json' \
    -d '{
      "nft_contract_address": "0x...",
      "network": "base",
      "recipients": [{"fid": 12345, "quantity": 1}]
    }'
  ```

  ```python Python theme={"system"}
  import requests

  headers = {
      'x-api-key': 'YOUR_NEYNAR_API_KEY',
      'x-wallet-id': 'your-wallet-id',
      'Content-Type': 'application/json'
  }

  response = requests.post(
      'https://api.neynar.com/v2/farcaster/nft/mint',
      headers=headers,
      json={
          'nft_contract_address': '0x...',
          'network': 'base',
          'recipients': [{'fid': 12345, 'quantity': 1}]
      }
  )

  result = response.json()
  print('Minted:', result)
  ```
</CodeGroup>

### Example: Buying Storage

<CodeGroup>
  ```javascript Node.js theme={"system"}
  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
    })
  });
  ```

  ```bash cURL theme={"system"}
  curl -X POST 'https://api.neynar.com/v2/farcaster/storage/buy' \
    -H 'x-api-key: YOUR_NEYNAR_API_KEY' \
    -H 'x-wallet-id: your-wallet-id' \
    -H 'Content-Type: application/json' \
    -d '{"fid": 12345, "units": 1}'
  ```
</CodeGroup>

## Error Handling

### Missing Wallet ID

If you don't provide a wallet\_id when required:

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

**Solution:** Add the `x-wallet-id` header or request allowlist access.

### Invalid Wallet ID

If your wallet\_id is incorrect:

```json theme={"system"}
{
  "code": "InvalidWalletId",
  "message": "The provided wallet_id is invalid or not found."
}
```

**Solution:** Verify your wallet\_id in the developer portal or contact support.

### Insufficient Balance

If your wallet runs out of gas:

```json theme={"system"}
{
  "code": "InsufficientFunds",
  "message": "Wallet does not have enough balance to complete this transaction."
}
```

**Solution:** Fund your wallet with more gas tokens.

## 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?

No, each app should have its own wallet\_id for security and accounting purposes.

### What happens if my wallet runs out of funds?

Operations will fail with an insufficient balance error. Fund your wallet to resume operations.

### Can I withdraw funds from my wallet?

Not currently. App wallets are managed by Neynar for security. Contact support if you need to adjust your setup.

### Can I see transaction history?

Yes, use a block explorer with your wallet address, or check the developer portal (coming soon).

## Related Documentation

<CardGroup cols={2}>
  <Card title="Mint NFTs" href="/docs/mint-for-farcaster-users" icon="image">
    Mint NFTs directly to Farcaster users
  </Card>

  <Card title="Buy Storage" href="/reference/buy-storage" icon="database">
    Purchase storage units for users
  </Card>

  <Card title="Create Accounts" href="/docs/how-to-create-a-new-farcaster-account-with-neynar" icon="user-plus">
    Register new Farcaster accounts
  </Card>

  <Card title="Fetch FIDs" href="/reference/get-fresh-account-fid" icon="hashtag">
    Get fresh FIDs for registration
  </Card>
</CardGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="Create App Wallet" href="https://dev.neynar.com" icon="wallet">
    Set up your wallet in the developer portal
  </Card>

  <Card title="Developer Portal" href="https://dev.neynar.com" icon="browser">
    Manage your apps and wallets
  </Card>

  <Card title="Get Support" href="https://t.me/rishdoteth" icon="telegram">
    Need help? Contact our team
  </Card>

  <Card title="Community Support" href="https://warpcast.com/~/channel/neynar" icon="messages">
    Ask questions in our Farcaster channel
  </Card>
</CardGroup>