B
Banksi/DocsSign In

Documentation

Banksi is a crypto payment service for banks. Integrate stablecoin payments via REST API, MCP for AI agents, or the x402 protocol for pay-per-use APIs.

AI Agents

MCP Server

Banksi includes a Model Context Protocol server. AI agents (Claude, etc.) can browse stores, create payments, check statuses, and handle x402 paywalls — all autonomously.

Setup

1. Run standalone

npm run mcp

2. Add to Claude Desktop / Claude Code

{
  "mcpServers": {
    "banksi": {
      "command": "npx",
      "args": ["tsx", "src/mcp/server.ts"],
      "cwd": "/path/to/banksi"
    }
  }
}

Tools

list_chains

List supported blockchains and their tokens (USDT/USDC)

Params: none

get_store

Get merchant store info and product catalog by slug

Params: slug: string

create_payment

Create a payment — returns unique deposit address

Params: slug, productId, chainId, tokenId

get_payment

Get full payment details with status

Params: paymentId: string

check_payment_status

Check on-chain payment status

Params: paymentId: string

x402_pay

Pay for an x402 paywalled API endpoint

Params: merchantSlug, chainId, tokenId, amount

Example Flow

Agent: list_chains
→ Ethereum (USDT, USDC), Arbitrum, BSC, Tron, Solana ...

Agent: get_store("seoul-coffee")
→ { merchant: "Seoul Coffee", products: [Americano $4.50, ...] }

Agent: create_payment("seoul-coffee", "prod_abc", "ethereum", "usdt_id")
→ { paymentId: "pay_xyz", address: "0xABC...", amount: "4.50 USDT" }

// ... user pays on-chain ...

Agent: check_payment_status("pay_xyz")
→ { status: "CONFIRMED", txHash: "0xDEF...", confirmations: 5 }

Programmable Payments

x402 Protocol

HTTP 402 "Payment Required" — reimagined for crypto. Protect any API endpoint with a paywall. Clients (including AI agents) pay on-chain and retry with proof of payment. No accounts, no API keys.

Flow

Client                          Banksi                      Blockchain
  │                                │                              │
  │  GET /api/x402/demo            │                              │
  │───────────────────────────────>│                              │
  │                                │                              │
  │  402 { paymentRequired: {      │                              │
  │    amount: 0.01, chains,       │                              │
  │    payUrl } }                  │                              │
  │<───────────────────────────────│                              │
  │                                │                              │
  │  POST /api/x402/pay            │                              │
  │  { merchantSlug, chainId,      │                              │
  │    tokenId, amount }           │                              │
  │───────────────────────────────>│                              │
  │                                │                              │
  │  201 { paymentId, address }    │                              │
  │<───────────────────────────────│                              │
  │                                │                              │
  │  Send USDT to address ─────────────────────────────────────>  │
  │                                │    Monitor detects payment   │
  │                                │<──────────────────────────── │
  │                                │                              │
  │  GET /api/x402/demo            │                              │
  │  X-Payment: <paymentId>        │                              │
  │───────────────────────────────>│                              │
  │                                │                              │
  │  200 { data: "premium" }       │                              │
  │<───────────────────────────────│                              │

Try It

The demo endpoint requires a $0.01 stablecoin payment:

1. Hit the protected endpoint

curl http://localhost:3001/api/x402/demo

Returns 402 with payment instructions

2. Create payment

curl -X POST http://localhost:3001/api/x402/pay \
  -H "Content-Type: application/json" \
  -d '{"merchantSlug":"seoul-coffee","chainId":"ethereum","tokenId":"<id>","amount":0.01}'

3. Pay on-chain, then retry with receipt

curl -H "X-Payment: <paymentId>" http://localhost:3001/api/x402/demo

Returns 200 with premium content

Protect Your Own Endpoint

import { requirePayment } from '@/lib/x402/middleware';

export async function GET(request: NextRequest) {
  const paywall = await requirePayment(request, {
    merchantSlug: 'your-store',
    amount: 0.05,
    description: 'Access this API for $0.05',
  });

  if (paywall) return paywall; // Returns 402

  // Payment verified — serve content
  return NextResponse.json({ data: '...' });
}

REST API

API Reference

Public endpoints — no authentication required.

GET/api/chains
GET/api/store/:slug
POST/api/store/:slug/pay
GET/api/payments/:id
GET/api/payments/:id/status
POST/api/x402/pay
GET/api/x402/demo
POST/api/upload