Falcon API SDK

🦅 Monetize your APIs with Stellar blockchain payments

Falcon API SDK enables developers to wrap their Express.js API endpoints with payment protection using the Stellar blockchain. Choose between Pay-per-User or Escrow payment modes.

Installation

npm install @anshu007/falcon-api-sdk

Quick Start

Run the interactive setup:

npx @anshu007/falcon-api-sdk init

This will ask you:

1. Payment Mode: Pay-per-User or Escrow
2. Wallet Address: Your Stellar wallet to receive payments
3. API Details: Name and price per call

Payment Modes

💳 Mode 1: Pay-per-User

Direct payment for each API call. User pays → API responds.

const express = require('express');
const { protect } = require('@anshu007/falcon-api-sdk');

const app = express();

app.get('/api/premium', protect({
  price: { amount: '5', asset: 'XLM' },
  receiver: 'GXXXXX...'  // Your wallet
}), (req, res) => {
  res.json({ 
    data: 'Premium content!',
    payer: req.paymentInfo.payer
  });
});

app.listen(3000);

How it works:

1. User calls your API
2. API returns 402 Payment Required with payment details
3. User pays via Stellar wallet (Freighter, etc.)
4. User retries with x-payment-tx header containing transaction hash
5. SDK verifies payment on Stellar blockchain
6. API returns premium content

🏦 Mode 2: Escrow (Prepaid)

Users prepay to escrow wallet, then consume credits on API calls.

const express = require('express');
const { protectWithEscrow, ESCROW_PUBLIC_KEY } = require('@anshu007/falcon-api-sdk');

const app = express();

console.log('Escrow Wallet:', ESCROW_PUBLIC_KEY);

app.get('/api/premium', protectWithEscrow({
  apiId: 'my-api',
  apiOwnerId: 'GXXXXX...',  // Your wallet
  pricePerCall: 5,
}), (req, res) => {
  res.json({ 
    data: 'Premium content!',
    remainingBalance: res.locals.escrowBalance
  });
});

app.listen(3000);

Escrow Wallet:

Public Key: GALFFRMVCGOPUHSXER3ZZKYHR25F4ISJFTLPEGX3UI4B63MPKUC75BLJ

How it works:

1. User funds escrow wallet with XLM
2. User records prepayment via your backend
3. User calls API with x-user-id or x-wallet-address header
4. SDK deducts credits from user's escrow balance
5. API returns content + remaining balance

API Reference

protect(config)

Pay-per-User middleware.

protect({
  price: {
    amount: '10',      // Price per call (XLM)
    asset: 'XLM'       // Payment asset
  },
  receiver: 'GXXX...', // Your Stellar wallet
  validateRequest: (req) => true  // Optional validator
})

protectWithEscrow(config)

Escrow middleware.

protectWithEscrow({
  apiId: 'my-api',           // Unique API ID
  apiOwnerId: 'GXXX...',     // Your Stellar wallet
  pricePerCall: 5,           // Price in XLM
  escrowServer: 'http://...' // Optional: custom escrow server
})

initEscrow(config)

Initialize escrow SDK for backend use.

const { initEscrow } = require('@anshu007/falcon-api-sdk');

const escrow = initEscrow();

// Record prepayment
await escrow.recordPrepayment({
  userId: 'GUSER...',
  txHash: 'abc123...',
  amount: 100
});

// Check balance
const { balance } = escrow.getUserBalance('GUSER...');

// Consume credits
escrow.consumeCredit({
  userId: 'GUSER...',
  apiId: 'my-api',
  apiOwnerId: 'GOWNER...',
  amount: 5
});

CLI Commands

# Interactive setup
npx @anshu007/falcon-api-sdk init

# Register API on marketplace
npx @anshu007/falcon-api-sdk register \
  --name "My API" \
  --description "Amazing API" \
  --endpoint "https://myapi.com/api/premium" \
  --price 5 \
  --wallet "GXXXXX..." \
  --mode escrow

# List registered APIs
npx @anshu007/falcon-api-sdk list

# Show escrow info
npx @anshu007/falcon-api-sdk escrow

# Help
npx @anshu007/falcon-api-sdk help

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | FALCON_REGISTRY | API registry URL | http://localhost:3001 | | FALCON_ESCROW_SERVER | Escrow server URL | http://localhost:3001 |

Escrow Wallet Info

For Escrow Mode:

Public Key:  GALFFRMVCGOPUHSXER3ZZKYHR25F4ISJFTLPEGX3UI4B63MPKUC75BLJ
Network:     Stellar Testnet

License

MIT © Falcon Labs