API Reference

Complete REST API documentation for Grapevine.

Base URLs

Quick Start

// 1. Install dependencies
bun add viem @coinbase/x402 x402
 
// 2. Create a feed
const feed = await fetch('https://api.grapevine.markets/v1/feeds', {
  method: 'POST',
  headers: { ...authHeaders, 'X-PAYMENT': paymentHeader },
  body: JSON.stringify({ name: 'My Feed' })
});
 
// 3. Add content
const entry = await fetch(`${API}/v1/feeds/${feed.id}/entries`, {
  method: 'POST',
  headers: { ...authHeaders, 'X-PAYMENT': paymentHeader },
  body: JSON.stringify({
    content_base64: btoa('Hello World'),
    mime_type: 'text/plain',
    is_free: true
  })
});

Core Resources

Feeds

Create and manage content feeds.

Endpoints: Create • List • Get • Update • Delete

Entries

Add content to feeds (text, JSON, images, video, etc).

Endpoints: Create • List • Get • Delete

Wallets

User profiles and statistics.

Endpoints: Get • Get by Address • Update • Stats

Transactions

Payment transaction history.

Endpoints: List • Get • Get by Hash

Leaderboards

Discovery and rankings (8 endpoints).

Endpoints: Recent • Top Feeds • Top Revenue • Top Providers • Top Buyers • Trending • Most Popular • Category Stats

Categories

Content categorization.

Endpoints: List • Get

Authentication

All write operations require wallet-based authentication.

• x-wallet-address
• x-signature
• x-message
• x-timestamp
• x-chain-id

Payments

Operations requiring payment use the x402 protocol.

1. Initial request → 402 Payment Required
2. Create payment with x402 client
3. Retry with X-PAYMENT header
4. Success → X-PAYMENT-RESPONSE header

External Playground

Try the API interactively:

• Mainnet: api.grapevine.fyi/v1/docs
• Testnet: api.grapevine.markets/v1/docs
• OpenAPI Spec: openapi.json

Rate Limits

• Authentication: 5 minute nonce expiry
• API Requests: 100 requests/minute per wallet
• Content Size: 50MB maximum
• Feed Limit: 10 feeds per wallet
• Entry Limit: 1000 entries per feed

Supported Networks

Next Steps

• Authentication - Set up wallet auth
• x402 Payments - Handle payments
• Quick Start - Complete tutorial