PayGo Network x402 API

Introduction

What is x402?

x402 is an HTTP payment protocol that uses the 402 Payment Required status code. When you call a paid endpoint without payment, you receive pricing details and payment instructions. After paying via blockchain, you retry with proof of payment to receive your result.

Authentication Flow

The x402 protocol uses a simple 3-step payment flow:

Step 1: Initial Request (402 Response)

curl -X POST https://paygo.network/api/x402/ocr/invoice \
  -H "Content-Type: application/json" \
  -d '{"file_url": "https://example.com/invoice.jpg"}'

Response (402 Payment Required):

{
  "request_id": "uuid",
  "payment_required": true,
  "status": 402,
  "payment_details": {
    "facilitator_url": "https://facilitator.payai.network",
    "amount": "0.080000",
    "currency": "USDC",
    "network": "solana",
    "recipient": "Do4wPLngMVyfBu4XKepo2Lpc5zGeYZdgqTtoNRM5B5D4",
    "payment_request_token": "JWT_TOKEN",
    "expires_at": 1762508014
  },
  "service": {
    "name": "Invoice OCR & Data Extraction",
    "description": "..."
  },
  "instructions": {
    "step1": "Complete payment using the facilitator URL",
    "step2": "Include the transaction signature in X-PAYMENT header",
    "step3": "Retry the request with X-PAYMENT header"
  }
}

Step 2: Make Payment

Send exactly 0.08 USDC to the recipient address on Solana. Use Phantom, Solflare, or any Solana wallet. You'll receive a transaction signature.

Step 3: Retry with Payment Proof

curl -X POST https://paygo.network/api/x402/ocr/invoice \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: " \
  -d '{"file_url": "https://example.com/invoice.jpg"}'

Response (200 OK):

{
  "success": true,
  "data": {
    "vendor": {
      "name": "Acme Corp",
      "address": "123 Main St",
      ...
    },
    "invoice": {
      "number": "INV-001",
      "date": "2025-11-07",
      ...
    },
    "totals": {
      "total": 1620.00
    }
  },
  "metadata": {
    "processing_time": 1234.56,
    "model": "gpt-4o-mini-2024-07-18"
  }
}

Available Endpoints

{
  "protocol": "x402",
  "version": "1.0",
  "facilitator": "https://facilitator.payai.network",
  "services": [
    {
      "id": "ocr-invoice",
      "name": "Invoice OCR & Data Extraction",
      "endpoint": "https://paygo.network/api/x402/ocr/invoice",
      "price": { "amount": 0.08, "currency": "USDC" },
      ...
    }
  ],
  "total": 2
}

{
  "vendor": {
    "name": "string",
    "address": "string",
    "phone": "string | null",
    "email": "string | null",
    "tax_id": "string | null"
  },
  "customer": {
    "name": "string | null",
    "address": "string | null"
  },
  "invoice": {
    "number": "string",
    "date": "YYYY-MM-DD",
    "due_date": "YYYY-MM-DD | null"
  },
  "line_items": [
    {
      "description": "string",
      "quantity": number,
      "unit_price": number,
      "amount": number
    }
  ],
  "totals": {
    "subtotal": number,
    "tax": number,
    "total": number
  }
}

{
  "merchant": {
    "name": "string",
    "address": "string | null",
    "phone": "string | null"
  },
  "transaction": {
    "date": "YYYY-MM-DD",
    "time": "HH:MM:SS | null",
    "transaction_id": "string | null"
  },
  "items": [
    {
      "name": "string",
      "quantity": number | null,
      "price": number
    }
  ],
  "totals": {
    "subtotal": number | null,
    "tax": number | null,
    "total": number
  },
  "payment": {
    "method": "string | null",
    "card_last_4": "string | null"
  }
}

{
  "success": true,
  "data": {
    "text": "Full transcription text...",
    "segments": [
      {
        "id": 0,
        "start": 0.0,
        "end": 5.5,
        "text": "Hello, this is a test."
      }
    ],
    "words": null,
    "language": "en",
    "duration": 120.5
  },
  "metadata": {
    "processing_time": 2341.23,
    "duration_minutes": 2.01,
    "model": "whisper-1"
  }
}

{
  "success": true,
  "data": {
    "transcription": {
      "text": "Full meeting transcript...",
      "language": "en",
      "duration": 1800.0,
      "segments": [...]  // if include_timestamps=true
    },
    "summary": "The meeting covered three main topics..."
  },
  "metadata": {
    "processing_time": 3241.56,
    "duration_minutes": 30.0,
    "models_used": ["whisper-1", "gpt-4o-mini"],
    "cost_breakdown": {
      "transcription": 0.180,
      "summary": 0.001
    }
  }
}

{
  "success": true,
  "data": {
    "text": "Full meeting transcript...",
    "segments": [
      {
        "id": 0,
        "start": 0.0,
        "end": 5.5,
        "text": "Good morning everyone.",
        "speaker": "Speaker 1"
      },
      {
        "id": 1,
        "start": 6.0,
        "end": 10.2,
        "text": "Thanks for joining the call.",
        "speaker": "Speaker 2"
      }
    ],
    "language": "en",
    "duration": 1800.0,
    "speaker_count": 2
  },
  "metadata": {
    "processing_time": 3841.78,
    "duration_minutes": 30.0,
    "model": "whisper-1",
    "speaker_identification": true
  }
}

Code Examples

JavaScript / Node.js

async function callX402Api(endpoint, payload) {
  // Step 1: Call without payment
  let response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });

  if (response.status === 402) {
    const paymentDetails = await response.json();

    // Step 2: Make payment (using Solana wallet)
    const txSignature = await makePayment(paymentDetails);

    // Step 3: Retry with payment proof
    response = await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-PAYMENT': txSignature
      },
      body: JSON.stringify(payload)
    });
  }

  return await response.json();
}

// Usage - OCR Invoice
const result = await callX402Api(
  'https://paygo.network/api/x402/ocr/invoice',
  { file_url: 'https://example.com/invoice.jpg' }
);

// Usage - Audio Transcription
const transcription = await callX402Api(
  'https://paygo.network/api/x402/transcribe/audio',
  {
    audio_url: 'https://example.com/audio.mp3',
    language: 'en',
    timestamp_granularities: ['segment']
  }
);

// Usage - Transcription with Summary
const summary = await callX402Api(
  'https://paygo.network/api/x402/transcribe/summary',
  {
    audio_url: 'https://example.com/meeting.mp3',
    language: 'en',
    include_timestamps: true
  }
);

// Usage - Meeting Transcription with Speakers
const meeting = await callX402Api(
  'https://paygo.network/api/x402/transcribe/meeting',
  {
    audio_url: 'https://example.com/meeting.mp3',
    identify_speakers: true
  }
);

Python

import requests

def call_x402_api(endpoint, payload):
    # Step 1: Call without payment
    response = requests.post(endpoint, json=payload)

    if response.status_code == 402:
        payment_details = response.json()

        # Step 2: Make payment (using Solana SDK)
        tx_signature = make_payment(payment_details)

        # Step 3: Retry with payment proof
        response = requests.post(
            endpoint,
            json=payload,
            headers={'X-PAYMENT': tx_signature}
        )

    return response.json()

# Usage - OCR Invoice
result = call_x402_api(
    'https://paygo.network/api/x402/ocr/invoice',
    {'file_url': 'https://example.com/invoice.jpg'}
)

# Usage - Audio Transcription
transcription = call_x402_api(
    'https://paygo.network/api/x402/transcribe/audio',
    {
        'audio_url': 'https://example.com/audio.mp3',
        'language': 'en',
        'timestamp_granularities': ['segment']
    }
)

# Usage - Transcription with Summary
summary = call_x402_api(
    'https://paygo.network/api/x402/transcribe/summary',
    {
        'audio_url': 'https://example.com/meeting.mp3',
        'language': 'en',
        'include_timestamps': True
    }
)

# Usage - Meeting Transcription with Speakers
meeting = call_x402_api(
    'https://paygo.network/api/x402/transcribe/meeting',
    {
        'audio_url': 'https://example.com/meeting.mp3',
        'identify_speakers': True
    }
)

PHP

function callX402Api($endpoint, $payload) {
    // Step 1: Call without payment
    $ch = curl_init($endpoint);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

    $response = curl_exec($ch);
    $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if ($statusCode === 402) {
        $paymentDetails = json_decode($response, true);

        // Step 2: Make payment (using Solana PHP SDK)
        $txSignature = makePayment($paymentDetails);

        // Step 3: Retry with payment proof
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'X-PAYMENT: ' . $txSignature
        ]);
        $response = curl_exec($ch);
    }

    curl_close($ch);
    return json_decode($response, true);
}

// Usage - OCR Invoice
$result = callX402Api(
    'https://paygo.network/api/x402/ocr/invoice',
    ['file_url' => 'https://example.com/invoice.jpg']
);

// Usage - Audio Transcription
$transcription = callX402Api(
    'https://paygo.network/api/x402/transcribe/audio',
    [
        'audio_url' => 'https://example.com/audio.mp3',
        'language' => 'en',
        'timestamp_granularities' => ['segment']
    ]
);

// Usage - Transcription with Summary
$summary = callX402Api(
    'https://paygo.network/api/x402/transcribe/summary',
    [
        'audio_url' => 'https://example.com/meeting.mp3',
        'language' => 'en',
        'include_timestamps' => true
    ]
);

// Usage - Meeting Transcription with Speakers
$meeting = callX402Api(
    'https://paygo.network/api/x402/transcribe/meeting',
    [
        'audio_url' => 'https://example.com/meeting.mp3',
        'identify_speakers' => true
    ]
);

cURL

# Step 1: Get payment details
curl -X POST https://paygo.network/api/x402/ocr/invoice \
  -H "Content-Type: application/json" \
  -d '{"file_url":"https://example.com/invoice.jpg"}'

# Step 2: Make payment via Solana wallet (get tx signature)

# Step 3: Retry with payment proof
curl -X POST https://paygo.network/api/x402/ocr/invoice \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: " \
  -d '{"file_url":"https://example.com/invoice.jpg"}'

# Audio Transcription Example
curl -X POST https://paygo.network/api/x402/transcribe/audio \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: " \
  -d '{"audio_url":"https://example.com/audio.mp3","language":"en","timestamp_granularities":["segment"]}'

# Transcription with Summary Example
curl -X POST https://paygo.network/api/x402/transcribe/summary \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: " \
  -d '{"audio_url":"https://example.com/meeting.mp3","include_timestamps":true}'

# Meeting Transcription Example
curl -X POST https://paygo.network/api/x402/transcribe/meeting \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: " \
  -d '{"audio_url":"https://example.com/meeting.mp3","identify_speakers":true}'

Resources

Additional Information