@blockia/server-sdk

Backend SDK for merchants to integrate Blockia Pay X402 protocol into their APIs. Enables pay-per-use endpoints and automatic payment processing.

Installation

npm install @blockia/server-sdk
# or
yarn add @blockia/server-sdk
# or
pnpm add @blockia/server-sdk

Quick Start

Basic Usage

import { BlockiaServer } from '@blockia/server-sdk';

const blockiaServer = new BlockiaServer({
  apiUrl: 'https://api.blockia.com',
  secretKey: 'sk_live_...', // Your secret key from Blockia dashboard
});

// Create a payment record
const paymentRecord = await blockiaServer.createPaymentRecord({
  amount: 9.99,
  description: 'Premium API Access',
  successUrl: 'https://yourapp.com/success',
  cancelUrl: 'https://yourapp.com/cancel',
});

console.log(paymentRecord.url); // Payment URL for customers

Express Middleware for X402 Protection

import express from 'express';
import { x402Middleware } from '@blockia/server-sdk';

const app = express();

// Protect endpoints with payment requirements
app.use(
  x402Middleware({
    secretKey: 'sk_live_...',
    protectedEndpoints: {
      '/api/premium/data': 0.1, // $0.10 per request
      '/api/premium/analytics': 0.5, // $0.50 per request
    },
  })
);

// Protected endpoint
app.get('/api/premium/data', (req, res) => {
  // Payment already verified by middleware
  const { recordId, transactionHash, amount } = req.payment;

  res.json({
    data: 'premium content',
    payment: { recordId, transactionHash, amount },
  });
});

app.listen(3000);

API Reference

BlockiaServer

Constructor

new BlockiaServer(config: BlockiaServerConfig)

Parameters:

• config.apiUrl: Base URL for the Blockia API
• config.secretKey: Your secret key for API authentication

Methods

createPaymentRecord(request: CreatePaymentRecordRequest): Promise

Creates a new payment record.

Parameters:

• request.amount: Payment amount (number)
• request.description: Payment description (string)
• request.successUrl?: URL to redirect after successful payment
• request.cancelUrl?: URL to redirect after cancelled payment
• request.metadata?: Custom metadata object
• request.expiresInHours?: Payment expiration time

validatePaymentRecord(recordId: string): Promise<ValidatePaymentRecordResponse>

Validates a payment record status.

getPaymentRecord(recordId: string): Promise<CreatePaymentRecordResponse>

Gets payment record details.

generateX402Requirements(recordId: string): Promise<X402PaymentRequirementsResponse>

Generates X402 payment requirements for a payment.

payWithX402(recordId: string, paymentRequest: X402PaymentRequest): Promise<PaymentSettlementResponse>

Processes an X402 payment.

Middleware

x402Middleware(config: X402MiddlewareConfig)

Express middleware that protects endpoints with X402 payments.

Config:

• secretKey: Your secret key
• protectedEndpoints: Object mapping endpoint paths to payment amounts
• apiUrl?: Custom API URL

x402Protect(secretKey: string, amount: number, apiUrl?: string)

Convenience function for protecting individual endpoints.

Agent Client SDK Updates

The Blockia Agent SDK now includes fetchWithPayment() for automatic X402 payment handling:

import { BlockiaAgent } from '@blockia/agent-sdk';

const agent = new BlockiaAgent({
  privateKey: '0x...',
  apiUrl: 'https://api.blockia.com',
});

// Automatically handles payments for protected endpoints
const response = await agent.fetchWithPayment(
  'https://api.example.com/premium/data'
);
const data = await response.json();

Error Handling

All methods throw errors for failed requests. Common errors:

• NetworkError: API communication failures
• ValidationError: Invalid parameters or responses

Environment Variables

BLOCKIA_API_URL=https://api.blockia.com
BLOCKIA_SECRET_KEY=sk_live_...

License

MIT