Valyn Core API Documentation

Valyn Core provides a complete platform for integrating x402 protocol into your applications. Enable instant, frictionless payments on BNB Chain with just a few lines of code.

Installation

Install the Valyn Core SDK using npm:

npm install @valyn/sdk

Or using yarn:

yarn add @valyn/sdk

Quick Start

Get started with Valyn Core in minutes:

Server Setup

import { ValynCore } from '@valyn/sdk';

const valyn = new ValynCore({
  network: 'bnb',
  apiKey: process.env.VALYN_API_KEY
});

// Enable x402 payments on your routes
app.use('/premium', valyn.middleware({
  price: '0.01',
  token: 'USDC'
}));

app.get('/premium/data', (req, res) => {
  res.json({ data: 'Premium content' });
});

Client Integration

import { ValynClient } from '@valyn/sdk';

const client = new ValynClient({
  privateKey: process.env.PRIVATE_KEY,
  network: 'bnb'
});

// Make a paid request
const response = await client.fetch(
  'https://api.example.com/premium/data'
);

const data = await response.json();

x402 Protocol Overview

The x402 protocol activates the HTTP 402 "Payment Required" status code, enabling seamless payment integration into web applications and APIs.

Key Features

• Zero Fees: No platform fees for merchants or customers
• Instant Settlement: Payments settle in ~2 seconds on BNB Chain
• No Registration: No accounts, KYC, or personal information required
• EIP-2612 Signatures: Secure gasless payments with permit signatures
• AI Agent Ready: Perfect for autonomous payment systems

Payment Flow

Understanding the x402 payment flow:

Step 1: Initial Request

GET /api/premium-data HTTP/1.1
Host: api.example.com

Step 2: Payment Required (402)

HTTP/1.1 402 Payment Required
X-Accept-Payment: USDC
X-Payment-Amount: 0.01
X-Payment-Address: 0x123...
X-Chain-ID: 56
X-Nonce: 12345

Step 3: Payment Submission

GET /api/premium-data HTTP/1.1
Host: api.example.com
X-Payment: {
  "signature": "0xabc...",
  "amount": "0.01",
  "token": "USDC",
  "timestamp": 1234567890
}

Step 4: Content Delivery

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": "Your premium content"
}

BNB Chain Integration

Valyn Core operates on BNB Smart Chain (BSC), providing fast and cost-effective transactions for payment processing.

Network Details

• Chain ID: 56 (BSC Mainnet)
• Settlement Time: ~2 seconds
• Gas Fees: Minimal (paid by relayer in gasless mode)
• Supported Tokens: USDC, USDT, BUSD

Smart Contract Configuration

const config = {
  chainId: 56,
  rpcUrl: 'https://bsc-dataseed.binance.org/',
  paymentContract: '0x...',  // x402 payment router
  usdcToken: '0x...',         // USDC on BSC
  gasless: true               // Enable EIP-2612 permits
};

API Endpoints

POST /api/payment

Process an x402 payment with automatic verification.

{
  "signature": "0xabc...",
  "amount": "0.01",
  "token": "USDC",
  "recipient": "0x123...",
  "nonce": 12345,
  "deadline": 1234567890
}

GET /api/balance

Check wallet balance and transaction history.

{
  "address": "0x123...",
  "balance": "100.00",
  "transactions": [...]
}

POST /api/webhook

Configure payment confirmation webhooks.

{
  "url": "https://your-app.com/webhook",
  "events": ["payment.completed", "payment.failed"]
}

Authentication

All API requests require authentication using an API key:

const headers = {
  'Authorization': `Bearer ${process.env.VALYN_API_KEY}`,
  'Content-Type': 'application/json'
};

Code Examples

Content Paywall

// Charge per article view
app.use(valyn.middleware({
  '/articles/:id': {
    price: '0.05',
    token: 'USDC'
  }
}));

app.get('/articles/:id', async (req, res) => {
  const article = await db.getArticle(req.params.id);
  res.json(article);
});

API Metering

// Different pricing per endpoint
app.use(valyn.middleware({
  '/api/translate': { price: '0.01' },
  '/api/analyze': { price: '0.10' },
  '/api/generate': { price: '0.25' }
}));

Autonomous AI Agents

// AI agent making autonomous payments
const agent = new AIAgent({
  wallet: new ValynClient({
    privateKey: agentPrivateKey,
    network: 'bnb'
  })
});

async function fetchData() {
  const urls = [
    'https://api1.com/data',
    'https://api2.com/data',
    'https://api3.com/data'
  ];
  
  const results = await Promise.all(
    urls.map(url => agent.wallet.fetch(url))
  );
  
  return results;
}

Additional Resources

• x402 Protocol Specification
• GitHub Repository
• Valyn Core Dashboard