xAPI-Fi

xAPI-Fi

Integration Guide

Learn how to integrate xAPI-Fi into your existing applications to start monetizing your APIs.

Quick Start

The fastest way to add xAPI-Fi to your application is using our middleware:

terminal
import { xapiFiMiddleware } from '@xapi-fi/sdk';

// Express.js
app.use('/api/premium', xapiFiMiddleware({
  apiKey: process.env.XAPI_FI_API_KEY,
  endpoint: '/premium-data',
}));

// Next.js API Route
export default xapiFiMiddleware({
  apiKey: process.env.XAPI_FI_API_KEY,
  endpoint: '/api/premium',
})(async (req, res) => {
  // Your premium endpoint logic
  res.json({ data: 'premium content' });
});

Framework Integration

Express.js

terminal
import express from 'express';
import { xapiFiMiddleware } from '@xapi-fi/sdk';

const app = express();

// Add xAPI-Fi to specific routes
app.get('/api/premium',
  xapiFiMiddleware({
    apiKey: process.env.XAPI_FI_API_KEY,
    endpoint: '/premium',
    priceUsd: 0.01, // $0.01 per request
  }),
  (req, res) => {
    res.json({ message: 'Premium data' });
  }
);

Next.js

terminal
// pages/api/premium.ts or app/api/premium/route.ts
import { xapiFiMiddleware } from '@xapi-fi/sdk';

export default xapiFiMiddleware({
  apiKey: process.env.XAPI_FI_API_KEY,
  endpoint: '/api/premium',
  priceUsd: 0.01,
})(async (req, res) => {
  return res.json({ data: 'premium content' });
});

NestJS

terminal
import { Injectable, NestMiddleware } from '@nestjs/common';
import { xapiFiMiddleware } from '@xapi-fi/sdk';

@Injectable()
export class XAPIFiMiddleware implements NestMiddleware {
  private middleware = xapiFiMiddleware({
    apiKey: process.env.XAPI_FI_API_KEY,
    endpoint: '/premium',
  });

  use(req: any, res: any, next: () => void) {
    this.middleware(req, res, next);
  }
}

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | Your xAPI-Fi API key from dashboard | | endpoint | string | Yes | Unique identifier for this endpoint | | priceUsd | number | No | Price per request in USD (default: 0.01) | | network | string | No | 'solana' or 'solana-devnet' (default: 'solana') | | facilitatorUrl | string | No | Custom facilitator URL (for self-hosting) |

Advanced Usage

Custom Payment Validation

terminal
import { xapiFiMiddleware, verifyPayment } from '@xapi-fi/sdk';

app.get('/api/custom', async (req, res) => {
  const paymentHeader = req.headers['x-payment'];

  const result = await verifyPayment({
    apiKey: process.env.XAPI_FI_API_KEY,
    endpoint: '/custom',
    paymentData: paymentHeader,
  });

  if (!result.valid) {
    return res.status(402).json({ error: 'Payment required' });
  }

  // Proceed with request
  res.json({ data: 'premium content' });
});

Webhook Integration

Configure webhooks in your dashboard to receive real-time payment notifications:

terminal
import { verifyWebhookSignature } from '@xapi-fi/sdk';

app.post('/webhooks/xapi-fi', async (req, res) => {
  const signature = req.headers['x-xapi-signature'];

  const isValid = verifyWebhookSignature({
    payload: req.body,
    signature,
    secret: process.env.XAPI_FI_WEBHOOK_SECRET,
  });

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook event
  const { event, data } = req.body;

  switch (event) {
    case 'payment.success':
      // Handle successful payment
      console.log('Payment received:', data);
      break;
    case 'payment.failed':
      // Handle failed payment
      console.log('Payment failed:', data);
      break;
  }

  res.json({ received: true });
});

Testing

Use your test API key for development:

terminal
xapiFiMiddleware({
  apiKey: process.env.XAPI_FI_TEST_KEY, // Test key from dashboard
  endpoint: '/test-endpoint',
  network: 'solana-devnet', // Use devnet for testing
})

Client-Side Integration

On the client side, users need to include payment proof in their requests:

terminal
import { createPayment } from '@xapi-fi/sdk/client';

// Create payment proof
const payment = await createPayment({
  endpoint: 'https://api.yourapp.com/premium',
  amount: 0.01,
  wallet: userWalletAddress,
});

// Include in request
const response = await fetch('https://api.yourapp.com/premium', {
  headers: {
    'x-payment': payment.proof,
  },
});

Best Practices

  1. ▹Use Environment Variables - Never hardcode API keys
  2. ▹Test with Devnet - Use Solana devnet for development
  3. ▹Handle Errors Gracefully - Always catch payment verification errors
  4. ▹Monitor Analytics - Check your dashboard for usage patterns
  5. ▹Set Appropriate Prices - Start low and adjust based on value

Troubleshooting

Payment Verification Fails

  • ▹Verify your API key is correct
  • ▹Check that the endpoint name matches your dashboard configuration
  • ▹Ensure the payment amount matches your endpoint price
  • ▹Confirm you're using the correct network (mainnet/devnet)

Middleware Not Working

  • ▹Make sure middleware is applied before your route handler
  • ▹Check that @xapi-fi/sdk is installed correctly
  • ▹Verify environment variables are loaded

Next Steps

Support