Skip to content

Home

Bridge402 API Documentation

  • Web2 to Web3 Bridge

    Access premium APIs using crypto payments instead of traditional credentials

    Getting Started

  • AI Agent Friendly

    Designed for autonomous agents that can make payments programmatically

    Payment Guide

  • Multi-chain Support

    Choose Base (EVM) or Solana for payments with seamless network switching

    Network Details

  • Developer Focused

    Simple REST and WebSocket APIs with comprehensive examples and docs

    Examples

Mission

Bridge402 bridges Web2 APIs to Web3 via x402 payments, enabling AI agents and Web3 applications to access premium APIs that were previously out of reach. By wrapping traditional APIs with crypto-native payment mechanisms, we make professional-grade data services accessible to the decentralized ecosystem.

Our Goal

Enable AI agents and decentralized applications to access premium APIs through seamless crypto payments, breaking down barriers between Web2 data services and Web3 innovation.

Services

Bridge402 currently provides four core services:

Service Description Pricing
News WebSocket Real-time crypto news streams via WebSocket $0.0035 USDC/min
Token-based discounts available
Earnings Transcripts Quarterly earnings call transcripts $0.05 USDC/doc
Diffbot Extraction Extract structured content from articles, products, and discussions $0.01 USDC/request
Diffbot Knowledge Graph Search Search the Diffbot Knowledge Graph using DQL queries $0.01 USDC/search

All services use the x402 payment protocol for pay-per-access, ensuring only paying users can access the data.

Table of Contents

Overview

Bridge402 operates on both Base (EVM) and Solana blockchains using USDC for payments. Our services provide:

  • Web2-to-Web3 Bridge: Access premium APIs using crypto payments instead of traditional credentials
  • AI Agent Friendly: Designed for autonomous agents that can make payments programmatically
  • Multi-chain Support: Choose Base or Solana for payments
  • Session Management: Flexible access control with automatic extension capabilities
  • Developer Focused: Simple REST and WebSocket APIs that work with any x402-compatible wallet

Base URL

https://bridge402.tech

Supported Networks

  • Base Mainnet (EVM)
  • USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

  • Uses EIP-3009 authorization flow

  • Solana Mainnet

  • USDC Mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
  • Uses Solana transaction-based payments

Authentication & Payment

All endpoints require x402 payment authentication using the X-PAYMENT header. The payment system uses:

  • Payment Methods: USDC on Base (EVM) or Solana networks
  • Rate: $0.0035 USDC per minute ($0.0175 for 5 minutes minimum)
  • Protocol: x402 "exact" scheme
  • Facilitator: PayAI Network
  • Network Selection: Use network query parameter to choose Base or Solana

Payment Flow

  1. Request Access: Make a request without X-PAYMENT header to receive payment requirements (optionally specify network=base or network=sol/network=solana)
  2. Choose Network: If no network specified, you'll receive payment options for both Base and Solana
  3. Generate Payment: Use x402 client to create payment authorization for your chosen network
  4. Submit Payment: Include X-PAYMENT header with base64-encoded payment data
  5. Access Granted: Receive access token for WebSocket connection

API Endpoints

Health Check

GET /healthz

Check service status and configuration.

Response: 

{
  "ok": true,
  "service": "bridge402",
  "rate_usdc_per_min": 0.0035,
  "min_minutes": 5,
  "tolerance_ppm": 5000,
  "tolerance_floor_atomic": 50,
  "base_url": "https://bridge402.tech",
  "supports": ["base (EVM USDC)", "solana (USDC)"],
  "facilitator_fee_payer": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4"
}

Connect to News Stream

POST /connect

Start a new streaming session with dynamic duration.

Query Parameters: - duration_min (optional): Session duration in minutes (1-120, default: 5) - network (optional): Choose payment network - base or sol/solana. If omitted, returns payment options for both networks. - wallet_address (optional): Solana wallet address for token-based pricing. When provided, the system queries your Bridge402 token balance and applies tiered pricing automatically.

Headers: - X-PAYMENT: Base64-encoded x402 payment data

Response (Success): 

{
  "access_token": "eyJzZXNzaW9uX2lkIjoi...",
  "expires_at": 1703123456.789,
  "payment": {
    "verified": true,
    "settled": true,
    "txHash": "0x1234...",
    "network": "base"
  }
}

Response (Payment Required - Single Network): If network parameter is specified, returns a single payment option: 

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "17500",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "BjxbJg48jQmoBLJnRunB1CMY5SZwvcUmnXCaWNeSXBei",
      "resource": "https://bridge402.tech/stream",
      "description": "Access to Bridge402 crypto news stream for 5 minute(s) [Solana/USDC]",
      "mimeType": "application/json",
      "maxTimeoutSeconds": 120,
      "extra": {
        "product": "Bridge402 News — 5 min (Solana)",
        "minutes": 5,
        "resourcePath": "/stream",
        "feePayer": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4"
      }
    }
  ]
}

Response (Payment Required - Both Networks): If no network parameter is specified, returns payment options for both Base and Solana: 

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "17500",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x745221d90e41193ee85c9d4679e40a9B57898A47",
      "resource": "https://bridge402.tech/stream",
      "description": "Access to Bridge402 crypto news stream for 5 minute(s) [Base/USDC]",
      "mimeType": "application/json",
      "maxTimeoutSeconds": 120,
      "extra": {
        "name": "USD Coin",
        "version": "2",
        "product": "Bridge402 News — 5 min (Base)",
        "minutes": 5,
        "resourcePath": "/stream"
      }
    },
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "17500",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "BjxbJg48jQmoBLJnRunB1CMY5SZwvcUmnXCaWNeSXBei",
      "resource": "https://bridge402.tech/stream",
      "description": "Access to Bridge402 crypto news stream for 5 minute(s) [Solana/USDC]",
      "mimeType": "application/json",
      "maxTimeoutSeconds": 120,
      "extra": {
        "product": "Bridge402 News — 5 min (Solana)",
        "minutes": 5,
        "resourcePath": "/stream",
        "feePayer": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4"
      }
    }
  ]
}

Note: Solana payments include a feePayer in the extra field, which is required for transaction construction. This is automatically fetched from the PayAI facilitator /supported endpoint.

Connect with Tiered Duration

POST /connect/{minutes}

Start a session with specific duration tier.

Path Parameters: - minutes: Session duration (1-120 minutes)

Query Parameters: - network (optional): Choose payment network - base or sol/solana

Headers: - X-PAYMENT: Base64-encoded x402 payment data

Response: Same as /connect

Extend Session

POST /extend

Extend an existing session duration.

Query Parameters: - duration_min (optional): Additional minutes to add (1-120, default: 5) - network (optional): Choose payment network - base or sol/solana. If omitted, detects network from payment payload. - wallet_address (optional): Solana wallet address for token-based pricing. When provided, the system queries your Bridge402 token balance and applies tiered pricing automatically.

Headers: - X-SESSION: Current access token - X-PAYMENT: Base64-encoded x402 payment data

Response: 

{
  "access_token": "eyJzZXNzaW9uX2lkIjoi...",
  "expires_at": 1703123456.789,
  "extended": true,
  "payment": {
    "verified": true,
    "settled": true,
    "txHash": "0x5678...",
    "network": "base"
  }
}

Get Earnings Transcript

POST /earnings-transcript

Retrieve earnings call transcripts from public companies. See the Earnings Transcripts documentation for comprehensive details, use cases, and integration examples.

Quick Example: 

# Get payment invoice
curl -X POST "https://bridge402.tech/earnings-transcript?symbol=AAPL&year=2024&quarter=1&network=sol"

# Get transcript with payment
curl -X POST "https://bridge402.tech/earnings-transcript?symbol=AAPL&year=2024&quarter=1&network=sol" \
  -H "X-PAYMENT: <base64-payment>"

Key Features: - Pay-per-access: $0.05 USDC per transcript (no subscription needed) - AI Agent Optimized: Perfect for autonomous agents that need financial data - Multi-chain: Supports both Base and Solana payments - Professional Data: Access earnings transcripts from major public companies

Diffbot Content Extraction

POST /diffbot/article, /diffbot/product, /diffbot/discussion, /diffbot/image

Extract structured content from web pages using Diffbot. See the Diffbot Extraction documentation for comprehensive details, use cases, and integration examples.

Quick Example: 

# Get payment invoice
curl -X POST "https://bridge402.tech/diffbot/article?url=https://example.com/article&network=sol"

# Get extraction with payment
curl -X POST "https://bridge402.tech/diffbot/article?url=https://example.com/article&network=sol" \
  -H "X-PAYMENT: <base64-payment>"

Key Features: - Pay-per-extraction: $0.01 USDC per request (no subscription needed) - Multiple Types: Extract articles, products, discussions, or images - AI Agent Optimized: Perfect for content analysis and aggregation - Multi-chain: Supports both Base and Solana payments - Computer Vision: Uses Diffbot's advanced extraction technology

WebSocket Streaming

Connect to Stream

WebSocket /stream?token={access_token}

Connect to the real-time crypto news stream.

Parameters: - token: Access token from /connect or /extend

Connection Flow: 1. Connect to WebSocket endpoint 2. Receive connection confirmation 3. Stream real-time news messages 4. Receive renewal prompts as session approaches expiry

Message Types:

Connection Confirmation: 

{
  "status": "connected",
  "service": "Bridge402"
}

News Messages:

Messages can be either Twitter/X posts or news articles.

Twitter/X Post: 

{
  "title": "stacks.btc (@Stacks)",
  "body": "we're excited to introduce a new companion...",
  "icon": "https://pbs.twimg.com/profile_images/...",
  "link": "https://twitter.com/Stacks/status/...",
  "coin": "STX",
  "actions": [...],
  "time": 1761945009301,
  "_id": "1984367309054755272"
}

News Article: 

{
  "title": "COINTELEGRAPH: MEXC apologizes to 'White Whale' trader over $3M freeze",
  "source": "Blogs",
  "url": "https://cointelegraph.com/news/...",
  "time": 1761945308076,
  "symbols": [],
  "_id": "1761945308075CMatWWto3f"
}

Renewal Prompt (Halfway): 

{
  "type": "renewal_prompt",
  "message": "You're halfway through your session. Extend now to avoid interruption (POST /extend with X-SESSION and X-PAYMENT).",
  "expires_at": 1703123456,
  "seconds_remaining": 150,
  "docs": {
    "extend_endpoint": "/extend",
    "headers": ["X-SESSION: <your access_token>", "X-PAYMENT: <base64 x402>"]
  }
}

Expiry Warning (30s before): 

{
  "type": "expiry_soon",
  "message": "Session expires in ~30 seconds. Extend via /extend to stay connected.",
  "expires_at": 1703123456,
  "seconds_remaining": 25
}

Session Extended: 

{
  "type": "session_extended",
  "message": "Session extended without disconnecting.",
  "expires_at": 1703123456,
  "seconds_remaining": 300
}

Error Handling

HTTP Status Codes

  • 200: Success
  • 400: Bad Request (invalid parameters)
  • 401: Unauthorized (invalid session token)
  • 402: Payment Required (missing or invalid payment)
  • 404: Not Found (session not found)
  • 500: Internal Server Error

Error Response Format

{
  "detail": "Error description",
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [...]
}

WebSocket Error Codes

  • 4000: General error
  • 4001: Invalid or expired token

Rate Limits & Pricing

Pricing Structure

  • News Stream:
  • Base Rate: $0.0035 USDC per minute
    • 5 minutes: $0.0175 USDC (17,500 atomic units)
    • 10 minutes: $0.035 USDC (35,000 atomic units)
    • 60 minutes: $0.21 USDC (210,000 atomic units)
  • Token-Based Pricing (Solana only): Hold Bridge402 tokens to unlock discounts
    • 0 tokens: $15/day ($0.0104/minute)
    • 2.5M tokens: $8/day ($0.0056/minute)
    • 5M+ tokens: $1/day ($0.000694/minute)
    • Linear interpolation between tiers
    • See Token-Based Pricing section for details
  • Earnings Transcripts: $0.05 USDC per document (50,000 atomic units)
  • Diffbot Extraction: $0.01 USDC per request (10,000 atomic units)
  • Article extraction: $0.01 USDC
  • Product extraction: $0.01 USDC
  • Discussion extraction: $0.01 USDC
  • Image extraction: $0.01 USDC
  • Diffbot Knowledge Graph Search: $0.01 USDC per search (10,000 atomic units)
  • Minimum Purchase: 5 minutes for news stream ($0.0175 USDC)

Session Management

  • Maximum Duration: 120 minutes per session
  • Extension: Unlimited extensions allowed
  • Grace Period: 5 seconds after expiry
  • Auto-disconnect: When session expires

Payment Requirements

  • Networks: Base mainnet (EVM) or Solana mainnet
  • Asset: USDC (6 decimals on both networks)
  • Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
  • Solana: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
  • Scheme: x402 "exact"
  • Timeout: 120 seconds for payment verification
  • Tolerance: 0.5% (5000 ppm) with 50 atomic unit floor
  • Solana-Specific:
  • Requires feePayer address (provided in invoice extra field)
  • Uses partial transaction signing (payer signs, facilitator completes)

Token-Based Pricing

Bridge402 offers tiered pricing for Solana users who hold Bridge402 tokens. The more tokens you hold, the lower your daily rate.

How It Works: 1. Provide your Solana wallet address via the wallet_address query parameter when requesting an invoice 2. The system automatically queries your Bridge402 token balance 3. Pricing is calculated based on your token holdings using linear interpolation 4. The invoice reflects your discounted rate

Pricing Tiers: - 0 tokens: $15/day ($0.0104/minute) - 1M tokens: ~$12.2/day ($0.0085/minute) - 2.5M tokens: $8/day ($0.0056/minute) - 5M+ tokens: $1/day ($0.000694/minute)

Token Details: - Token Mint: 86Qzt4Dpx51pYGj7TscfEEBbTspsnQJQpNQxodm6pump - Network: Solana Mainnet - Pricing Calculation: Linear interpolation between tiers - Automatic: No manual configuration needed - just provide your wallet address

Example Request: 

curl -X POST "https://bridge402.tech/connect?duration_min=60&network=sol&wallet_address=YOUR_SOLANA_WALLET_ADDRESS"

Invoice Response (with token-based pricing): 

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "41667",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "extra": {
        "tokenBalance": 2500000,
        "pricePerDay": 8.0,
        "product": "Bridge402 News — 60 min (Solana)"
      }
    }
  ]
}

Benefits: - Automatic discount calculation - No subscription required - Works with existing payment flow - Transparent pricing in invoice response

Examples

Complete implementation examples are available in the /examples folder. See the Examples README for detailed usage instructions.

Available Examples:

Quick Start:

# Install dependencies for Node.js Solana example
npm install undici ws dotenv @solana/web3.js @solana/spl-token

# Set environment variables
export KEYPAIR_PATH="id.json"
export BASE_URL="https://bridge402.tech"
export SOLANA_RPC="https://api.mainnet-beta.solana.com"

# Run Solana WebSocket client
node examples/prod-test-sol.js

# Run Diffbot extraction client
node examples/diff.js

# Or for Python examples
pip install -r examples/requirements.txt
python examples/transcript_client.py --symbol AAPL --year 2024 --quarter 1

Support

For technical support or questions about the API, please refer to the service logs or contact the development team.