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

``bash
npm install @anshu007/falcon-api-sdk
`

Quick Start

Run the interactive setup:

`bash
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

$3

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

`javascript
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

---

$3

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

`javascript
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

$3

Pay-per-User middleware.

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

$3

Escrow middleware.

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

$3

Initialize escrow SDK for backend use.

`javascript
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

`bash


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