Testing Guide

Learn how to test your Grapevine integration on Base Sepolia testnet.

Test Environment

Base Sepolia Testnet

API URL: https://api.grapevine.markets
Chain ID: 84532
Currency: Test USDC
Network: base-sepolia

Production

API URL: https://api.grapevine.fyi
Chain ID: 8453
Currency: USDC
Network: base

Getting Test Tokens

Base Sepolia ETH

Get test ETH for gas fees:

Alchemy Faucet: https://www.alchemy.com/faucets/base-sepolia

Visit the faucet
Connect your wallet
Request test ETH
Wait for confirmation

Test USDC

Get test USDC for payments:

Bridge from Ethereum Sepolia
- Get Sepolia ETH
- Get Sepolia USDC
- Bridge to Base Sepolia
Community Faucets
- Check Base Discord
- Community test token faucets
Contact Support
- Reach out to Grapevine support
- Request test USDC allocation

Using the Test Script

We provide a comprehensive test script that demonstrates the complete API workflow.

Installation

# Clone or download the test script
cd grapevine-docs-draft
 
# Install dependencies
bun install
 
# Configure environment
cp .env.example .env

Configuration

Edit .env:

PRIVATE_KEY=0x_your_test_wallet_private_key
API_URL=https://api.grapevine.markets

Running Tests

# Run with Bun (recommended)
bun run test-grapevine.ts
 
# Run with npm
npm run start
 
# Run with Node.js
node --loader tsx test-grapevine.ts

What It Tests

Authentication
- Nonce request
- Message signing
- Header generation
Feed Creation
- POST request
- 402 payment handling
- Payment processing
- Feed verification
Entry Creation
- Multiple content types
- Free entries
- Paid entries
- Batch creation
Verification
- List entries
- Count statistics
- Content type distribution

Output Files

Results are saved to runtime-specific files:

test-results-bun.json
test-results-npm.json
test-results-node.json

Example Output

╔════════════════════════════════════════╗
║     Grapevine API Test Script          ║
╚════════════════════════════════════════╝
 
━━━ Configuration ━━━
 
ℹ  Runtime: BUN (native APIs)
ℹ  Wallet Address: 0x1234...5678
ℹ  Network: base-sepolia (Chain ID: 84532)
ℹ  Wallet ETH balance: 0.0250 ETH
 
━━━ Creating Feed ━━━
 
ℹ  Feed Name: Test Feed from Bun Script
⚠  Payment required (402 response)
ℹ  Creating payment for 1000000 USDC on base-sepolia
✓  Payment processed successfully
✓  Feed created: 123e4567-e89b-12d3-a456-426614174000
 
━━━ Creating Entries ━━━
 
ℹ  Creating FREE entries...
✓  Entry created: abc123... (CID: QmX...)
✓  Entry created: def456... (CID: QmY...)
 
ℹ  Creating PAID entries...
⚠  Payment required (402 response)
✓  Payment processed successfully
✓  Entry created: ghi789... (CID: QmZ...)
 
━━━ Verification ━━━
 
✓  Total entries in feed: 10
ℹ  Free entries: 5
ℹ  Paid entries: 5
 
━━━ Entry Summary ━━━
 
ℹ  Content types created:
ℹ    text/plain: 2 entries
ℹ    application/json: 2 entries
ℹ    text/markdown: 2 entries
ℹ    text/html: 2 entries
ℹ    image/svg+xml: 2 entries
 
━━━ Access URLs ━━━
 
ℹ  Feed URL: https://api.grapevine.markets/v1/feeds/123e4567...
ℹ  Entries URL: https://api.grapevine.markets/v1/feeds/123e4567.../entries
ℹ  Web UI: https://www.grapevine.markets/feeds/123e4567...
 
✓  Results saved to test-results-bun.json
 
━━━ Test Complete! 🎉 ━━━
 
✓  Successfully created feed with 10 new entries

Manual Testing

Test Feed Creation

# 1. Get nonce
curl -X POST https://api.grapevine.markets/v1/auth/nonce \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"0xYourAddress"}'
 
# 2. Sign the returned message with your wallet
 
# 3. Create feed (will return 402)
curl -X POST https://api.grapevine.markets/v1/feeds \
  -H "Content-Type: application/json" \
  -H "x-wallet-address: 0xYourAddress" \
  -H "x-signature: 0xYourSignature" \
  -H "x-message: SignedMessage" \
  -H "x-timestamp: 1234567890" \
  -H "x-chain-id: 84532" \
  -d '{"name":"Test Feed"}'
 
# 4. Handle payment and retry with X-PAYMENT header

Test Entry Creation

# Create a text entry
curl -X POST https://api.grapevine.markets/v1/feeds/{feed_id}/entries \
  -H "Content-Type: application/json" \
  -H "x-wallet-address: 0xYourAddress" \
  -H "x-signature: 0xYourSignature" \
  -H "x-message: SignedMessage" \
  -H "x-timestamp: 1234567890" \
  -H "x-chain-id: 84532" \
  -d '{
    "content_base64": "SGVsbG8gV29ybGQ=",
    "mime_type": "text/plain",
    "title": "Test Entry",
    "is_free": true
  }'

Debugging Tests

Enable Debug Mode

DEBUG=true bun test-grapevine.ts

This shows:

Request URLs
Request headers
Response status
Response bodies
Payment details

Check Wallet Balance

import { createPublicClient, http } from 'viem';
import { baseSepolia } from 'viem/chains';
 
const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http()
});
 
const balance = await publicClient.getBalance({
  address: '0xYourAddress'
});
 
console.log(`Balance: ${Number(balance) / 1e18} ETH`);

Verify Network

const chainId = await publicClient.getChainId();
console.log(`Chain ID: ${chainId}`); // Should be 84532 for testnet

Common Issues

Low ETH Balance

⚠  Low ETH balance! You may need more ETH for gas fees.
ℹ  Get test ETH from: https://www.alchemy.com/faucets/base-sepolia

Solution: Get more test ETH from the faucet.

Insufficient USDC

✗  Payment failed: Insufficient USDC balance

Solution: Get test USDC or use a different wallet.

Network Mismatch

✗  Payment requirements don't match network

Solution: Ensure API_URL matches your intended network.

Authentication Expired

✗  Nonce has expired

Solution: The script handles this automatically, but you can request a fresh nonce.

Best Practices

Use Separate Test Wallet
- Don't use your mainnet wallet for testing
- Create a dedicated test wallet
Start Small
- Test with single feed first
- Add one entry before batch operations
Monitor Balances
- Check ETH balance before running
- Ensure sufficient USDC for payments
Save Test Results
- Keep test-results.json files
- Track feed IDs for debugging
Rate Limiting
- Add delays between requests
- Don't exceed 100 requests/minute

Moving to Production

When ready for mainnet:

Update Configuration

API_URL=https://api.grapevine.fyi
PRIVATE_KEY=0x_your_mainnet_wallet_key

Get Real USDC
- Buy USDC on exchange
- Bridge to Base network
Test Carefully
- Start with small amounts
- Verify all operations work
Monitor Costs
- Track payment amounts
- Monitor transaction fees

Next Steps

Quick Start - Basic setup
Error Handling Guide - Comprehensive error handling patterns
x402 Payments - Understand payment flow
Error Handling - Handle test failures