BlokPay

Send home. On chain. Instant fiat out.

🔗 Live App: https://blokpay.vercel.app

BlokPay enables instant, transparent cross-border remittances for the African diaspora: send stablecoins (USDC) from anywhere via blockchain escrow on Polygon/Base, and let your loved ones in Nigeria receive fiat NGN directly to their bank account in seconds using Interswitch Transfers — cheaper, faster, and fully on-chain trackable.

---

How to Use BlokPay

Getting Started (For Non-Crypto Users!)

BlokPay is designed for everyone - you don't need to know anything about cryptocurrency! Here's how to get started:

Step 1: Connect Your Wallet

1. Visit blokpay.vercel.app
2. Click "Get Started" or "Send Money"
3. Connect using one of these options:
   • 📧 Email (EASIEST for beginners) - Just enter your email, we'll create a wallet for you automatically!
   • 📱 Phone Number - Sign in with your mobile number
   • 🔗 Google/Apple - Use your existing Google or Apple account
   • 🦊 External Wallet - Connect MetaMask, Coinbase Wallet, or Rainbow

💡 Tip: If you're new to crypto, choose Email - it's the easiest way to get started!

Step 2: Get Test USDC (For Testing on Base Sepolia)

Before sending real money, you can test with free test tokens:

1. Get Your Wallet Address:

   • After connecting, go to the Receive page in the navigation
   • Copy your wallet address (starts with 0x...)

2. Get Free Test USDC:

   • Visit: https://faucet.circle.com/
   • Select Base (Sepolia) network
   • Paste your wallet address
   • Click Request USDC
   • Wait a few minutes for tokens to arrive

3. Verify: Your balance should now show in the dashboard

Step 3: Send Money to Nigeria

Option A: Send to Bank Account (Recommended)

This sends NGN directly to any Nigerian bank account:

1. Enter the amount in USDC you want to send
2. View the NGN conversion and fee breakdown
3. Select "Send to Bank Account"
4. Choose the Nigerian bank from the dropdown
5. Enter the recipient's account number
6. Click "Verify Recipient" - we'll confirm the account name with Interswitch
7. Confirm: "Yes, this is correct"
8. Click "Deposit & Send"
9. Wait for on-chain confirmation (~10-15 seconds)
10. Done! NGN is sent instantly to the bank account

Option B: Send Directly to Wallet

Send USDC directly to another crypto wallet:

1. Toggle to "Send to Wallet Address"
2. Enter the recipient's wallet address
3. Select the network (Base or Polygon)
4. Click "Send Direct"

---

Important Notes

First-Time Users

• On your first deposit, you may need to approve USDC spending in your wallet
• This is a one-time setup - your wallet will prompt you
• After approval, subsequent deposits are instant

Testnet vs Production

Feature	Testnet (Base Sepolia)	Production
Network	Base Sepolia	Base / Polygon
USDC	Free from faucet	You need to buy USDC
Gas Fees	Gasless (CDP Paymaster)	May apply
Get USDC	https://faucet.circle.com	Buy from exchange

Fees

• Platform Fee: 1.5% (vs 5-7% at Western Union)
• Network Fees: Minimal (often $0 on Base with gasless transactions)

Security

• USDC is held in a secure smart contract escrow
• Bank account verification prevents fraud
• All transactions are on-chain and traceable

---

Need Help?

Why was my transfer rejected?

• Check that the account number is correct
• Ensure the bank supports NGN transfers

How long does it take?

• On-chain deposit: ~10-15 seconds
• Bank payout: Instant (within seconds via Interswitch)

Questions?

Contact our support team or check the transaction history in your dashboard.

Team Contributions

Moses Sunday - Technical Lead

Core Development:

• Smart contract development & deployment (BlokPayEscrow.sol)
• Smart contract deployment on Base Sepolia & Polygon Amoy
• Frontend architecture & implementation (React + TypeScript)
• Wagmi/Privy/Web3 wallet integration
• CDP Paymaster & gasless transactions setup
• Multi-chain support (Base Sepolia + Polygon Amoy)

Backend & Infrastructure:

• Supabase edge functions (relayer-deposit, relayer-claim, relayer-refund)
• Interswitch Transfers API integration
• Webhook handlers for payment processing
• Database schema design with RLS policies
• Vercel deployment & CI/CD

---

Emmanuel Deji - Design & Research

UI/UX Design:

• Complete UI/UX design & prototyping
• Branding & visual identity development
• Logo design & favicon creation
• Color palette & typography system
• Component design & interactions
• Mobile-responsive design layouts

Product Research:

• User flow research & optimization
• Market analysis & competitor research
• Compliance & regulatory research
• Interswitch API documentation research
• Product positioning & messaging
• Demo presentation design

Brand Identity

Color Palette

Element	Color	Hex
Primary	Orange	#F96332
Background	Dark Navy Blue	#101D2D
Surface/Cards	Dark Gray	#18181B
Border	Gray	#27272A
Success	Orange	#F96332
Text Primary	White	#FFFFFF
Text Secondary	Gray	#A1A1AA

Features

• Instant Payouts: Interswitch integration routes NGN directly to any Nigerian bank account in seconds
• On-Chain Escrow: USDC is locked in a smart contract. Funds only release when the receiver verifies their claim
• Fraction of the Fee: 1.5% platform fee vs 5–7% at Western Union. Keep more money in your family's hands
• Transparent: Track your remittance on-chain with Polygonscan integration
• Secure Account Verification: Account Name Inquiry prevents fraud by verifying receiver account details match sender's intent
• Gasless Transactions: Senders pay zero gas fees via CDP Paymaster (Base) or owner relayer (Polygon)
• Multi-Chain Support: Choose between Base Sepolia or Polygon Amoy networks

Tech Stack

• Frontend: Vite 6 + React 18 + TypeScript (strict)
• Styling: Tailwind CSS + shadcn/ui (customized to exact colors)
• State Management: Zustand (wallet connection state)
• Blockchain: Multi-chain support (Base Sepolia + Polygon Amoy)
• Token: USDC (on both networks)
• API/BE: Supabase Edge Functions (Deno/TypeScript)
• Database: Supabase PostgreSQL with Row Level Security (RLS)
• API Integration: Interswitch Transfers API (sandbox)
• Authentication: Privy (email/phone + embedded wallet)
• Icons: Lucide React (minimal)
• Deployment: Vercel (frontend), Supabase (functions + database)

User Flow

Complete Remittance Flow (Bank Transfer)

sequenceDiagram
    participant S as Sender (Diaspora)
    participant F as BlokPay Frontend
    participant B as Blockchain
    participant A as Supabase Backend
    participant I as Interswitch API
    participant R as Receiver (Nigeria)

    Note over S,R: SENDER FLOW
    S->>F: Opens app & connects wallet
    F->>F: Privy authentication
    S->>F: Enters USDC amount
    F->>F: Shows NGN conversion (CoinGecko)
    S->>F: Selects bank & enters account number
    F->>I: Account Name Inquiry (Interswitch)
    I-->>F: Returns account name (e.g., "Chinedu Okoro")
    F->>S: Shows verified account name
    S->>F: Confirms "Yes, this is correct"
    S->>F: Clicks "Deposit & Send"
    F->>B: Contract.deposit()
    B-->>B: USDC locked in escrow
    B->>F: Transaction hash
    F->>A: Creates transaction record
    A->>I: Single Transfer API
    I->>R: NGN to bank account
    F->>S: Shows receipt with tx hash

    Note over S,R: RECEIVER EXPERIENCE
    R->>R: Receives NGN in bank account
    R-->>S: No action required!

Loading

Direct Wallet Transfer Flow

sequenceDiagram
    participant S as Sender (Diaspora)
    participant F as BlokPay Frontend
    participant B as Blockchain

    S->>F: Opens app & connects wallet
    S->>F: Toggles "Send to Wallet Address"
    S->>F: Enters recipient wallet address
    S->>F: Clicks "Send Direct"
    F->>B: Direct USDC transfer
    B-->>B: USDC transferred
    B->>F: Transaction hash
    F->>S: Shows receipt with tx hash

Loading

Sender Flow (Step by Step)

flowchart TD
    A[Landing Page] --> B[Connect Wallet]
    B --> C[Privy Auth]
    C --> D[Dashboard]
    D --> E[Click Send Money]
    E --> F[Enter USDC Amount]
    F --> G[View Fee Breakdown]
    G --> H{Select Transfer Method}
    H -->|Bank Transfer| I[Select Bank]
    H -->|Direct Wallet| P[Enter Wallet Address]
    I --> J[Enter Account Number]
    J --> K[Verify Account Name<br/>Interswitch API]
    K --> L[Confirm Account Name]
    P --> Q[Select Network]
    L --> M[Click Deposit & Send]
    Q --> M
    M --> N{Chain Selection}
    N -->|Base| O[CDP Paymaster<br/>Gasless]
    N -->|Polygon| R[Owner Relayer<br/>Gas Sponsorship]
    O --> S[USDC Deposited to Escrow]
    R --> S
    S --> T[Interswitch Transfer<br/>NGN to Bank]
    T --> U[Show Receipt]
    P --> U[Show Receipt]

Loading

System Architecture

graph TB
    subgraph "Client Layer"
        A[Web Browser] --> B[React Frontend]
        B --> C[Privy Auth]
        B --> D[Wagmi/viem]
    end

    subgraph "Blockchain Layer"
        E[Base Sepolia] --> F[Escrow Contract<br/>0x1D47170a23fCbdf...]
        G[Polygon Amoy] --> H[Escrow Contract<br/>0xF3D8e706...]
        F --> I[USDC Token]
        H --> I
    end

    subgraph "Gas Sponsorship"
        F --> J[CDP Paymaster]
        H --> K[Owner Relayer]
    end

    subgraph "Backend Layer"
        L[Supabase Edge Functions]
        L --> M[relayer-deposit-polygon]
        L --> N[relayer-claim]
        L --> O[relayer-refund-polygon]
        L --> P[interswitch-transfer]
    end

    subgraph "Database"
        Q[(PostgreSQL)]
        Q --> R[users]
        Q --> S[transactions]
        Q --> T[claims]
    end

    subgraph "External APIs"
        U[CoinGecko API<br/>FX Rates]
        V[Interswitch API<br/>Transfers]
        W[Polygonscan<br/>Block Explorer]
    end

    D --> E
    D --> G
    L --> V
    L --> U
    B --> L

Loading

Supported Networks

Network	Chain ID	Native Currency	USDC Address	Escrow Contract Address	Block Explorer
Base Sepolia	84532	ETH	0x036CbD53842c5426634e7929541eC2318f3dCF7e	0x1D47170a23fCbdf148a43474ecFFaE7E5384E49a	Basescan
Polygon Amoy	80002	MATIC	0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582	0xF3D8e7068ed8266e2Fd18fAa20403E2a67c700Da	Polygonscan

Note: Base Sepolia uses CDP Paymaster for gasless transactions. Polygon Amoy uses owner-funded relayer for gas sponsorship.

Interswitch API Integration

BlokPay uses the Interswitch Quickteller Service API for transferring NGN to Nigerian bank accounts.

API Base URLs

Environment	Base URL
Sandbox	https://qa.interswitchng.com
Production	https://api.interswitchng.com

Authentication

All Interswitch API requests require OAuth 2.0 authentication:

# Step 1: Generate Base64 encoded credentials
# clientId:clientSecret (base64 encoded)

# Step 2: Get Access Token
curl -X POST 'https://qa.interswitchng.com/passport/oauth/token?grant_type=client_credentials' \
  -H "Authorization: Basic {BASE64_ENCODED_CREDENTIALS}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=client_credentials'

# Response:
{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86400
}

API Endpoints Used

1. Get Bank Codes

Purpose: Retrieve list of Nigerian banks with their codes for dropdown selection.

GET https://qa.interswitchng.com/quicktellerservice/api/v5/configuration/fundstransferbanks
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json
TerminalID: {TERMINAL_ID}

Response:

{
  "banks": [
    {
      "id": "31",
      "cbnCode": "044",
      "bankName": "Access Bank Nigeria Plc",
      "bankCode": "ABP"
    },
    {
      "id": "10",
      "cbnCode": "058",
      "bankName": "Guaranty Trust Bank Plc",
      "bankCode": "GTB"
    }
  ]
}

2. Account Name Inquiry (Name Enquiry)

Purpose: Verify account number and get account holder's name before transfer.

GET https://qa.interswitchng.com/quicktellerservice/api/v5/transactions/DoAccountNameInquiry
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json
TerminalId: {TERMINAL_ID}
bankCode: {BANK_CODE}
accountId: {ACCOUNT_NUMBER}

Response:

{
  "AccountName": "VICTOR ADEKUNLE ODEBODE",
  "ResponseCode": "90000",
  "ResponseCodeGrouping": "SUCCESSFUL"
}

3. Single Transfer (Fund Transfer)

Purpose: Transfer NGN from BlokPay's account to the receiver's bank account.

POST https://qa.interswitchng.com/quicktellerservice/api/v5/transactions/TransferFunds
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json
terminalId: {TERMINAL_ID}

Request Body:

{
  "transferCode": "030009998999",
  "mac": "{SHA512_HASH}",
  "termination": {
    "amount": "160000",
    "accountReceivable": {
      "accountNumber": "3001155245",
      "accountType": "00"
    },
    "entityCode": "044",
    "currencyCode": "566",
    "paymentMethodCode": "AC",
    "countryCode": "NG"
  },
  "sender": {
    "phone": "08124888436",
    "email": "sender@example.com",
    "lastname": "Sender",
    "othernames": "Name"
  },
  "initiatingEntityCode": "PBL",
  "initiation": {
    "amount": "160000",
    "currencyCode": "566",
    "paymentMethodCode": "CA",
    "channel": "7"
  },
  "beneficiary": {
    "lastname": "Receiver",
    "othernames": "Name"
  }
}

Response:

{
  "MAC": "9f4e4f53c57be63e...",
  "TransactionDate": "03/Feb/2023 03:47:064",
  "TransactionReference": "PBL|LOC|CA|ABP|AC|030223154706|U4AN48D7",
  "ResponseCode": "90000",
  "ResponseCodeGrouping": "SUCCESSFUL"
}

4. Transaction Query (Optional - for status checks)

Purpose: Query the status of a previous transfer.

POST https://qa.interswitchng.com/quicktellerservice/api/v5/transactions/QueryTransaction
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json
terminalId: {TERMINAL_ID}

Response Codes

Code	Meaning
90000	Transaction successful
90001	Transaction pending
90002	Transaction failed
70120	Beneficiary bank unavailable (circuit breaker)

Integration in BlokPay

The Interswitch integration enables:

1. Bank Selection: Users select from list of Nigerian banks via Get Bank Codes
2. Account Verification: Account Name Inquiry prevents fraud by verifying receiver details
3. Instant Payout: Single Transfer delivers NGN to receiver's bank account within seconds
4. Transaction Tracking: Query API allows status verification

Note: Sandbox has limitations (₦10,000 max). Production requires full merchant onboarding.

Smart Contract

BlokPayEscrow.sol

The escrow smart contract handles secure storage of USDC until claims are verified.

Deployed Addresses:

• Base Sepolia: 0x1D47170a23fCbdf148a43474ecFFaE7E5384E49a
• Polygon Amoy: 0xF3D8e7068ed8266e2Fd18fAa20403E2a67c700Da

Key Functions:

Function	Description
deposit(receiver, amount, claimCode)	Lock USDC in escrow with claim code
depositByRelayer(sender, receiver, amount, claimCode)	Relayer-sponsored deposit (Polygon)
claim(claimCode, recipient)	Release USDC to recipient
claimByRelayer(claimCode, recipient)	Relayer-sponsored claim (Polygon)
refund(claimCode)	Refund expired escrow to sender
refundByRelayer(claimCode)	Relayer-sponsored refund (Polygon)
getEscrow(claimCode)	View escrow details

Installation

# Clone the repository
git clone https://github.com/Moses-main/blokpay.git
cd blokpay

# Install dependencies
pnpm install

# Start development server
pnpm dev

Environment Variables

Frontend (.env)

VITE_PRIVY_APP_ID=your_privy_app_id
VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
VITE_POLYGON_AMOY_ESCROW_ADDRESS=0xF3D8e7068ed8266e2Fd18fAa20403E2a67c700Da
VITE_BASE_SEPOLIA_ESCROW_ADDRESS=0x1D47170a23fCbdf148a43474ecFFaE7E5384E49a
VITE_CDP_PAYMASTER_URL=your_cdp_paymaster_url

Supabase Secrets

BLOKPAY_PRIVATE_KEY=your_owner_private_key
ESCROW_ADDRESS_POLYGON_AMOY=0xF3D8e7068ed8266e2Fd18fAa20403E2a67c700Da
POLYGON_AMOY_RPC_URL=https://rpc-amoy.polygon.technology/
INTERSWITCH_CLIENT_ID=your_interswitch_client_id
INTERSWITCH_CLIENT_SECRET=your_interswitch_client_secret

Project Structure

blokpay/
├── public/
│   ├── blokpay_logo.png      # Main logo
│   ├── blokpay_fav.png       # Favicon
│   └── blokpay_mobile.png    # Mobile logo
├── src/
│   ├── components/          # React components
│   │   ├── layout/          # Layout components
│   │   └── ui/              # shadcn/ui components
│   ├── hooks/               # Custom React hooks
│   │   └── useEscrow.ts     # Escrow interaction hooks
│   ├── lib/                 # Utilities
│   │   ├── contract.ts      # Contract ABIs & addresses
│   │   ├── wagmi.ts         # Wagmi configuration
│   │   ├── privy.tsx        # Privy provider
│   │   └── store.ts         # Zustand store
│   └── pages/               # Page components
│       ├── Send.tsx         # Send money flow
│       ├── Claim.tsx        # Claim funds flow
│       ├── Dashboard.tsx   # User dashboard
│       └── ...
├── contracts/               # Smart contracts
│   └── src/
│       └── BlokPayEscrow.sol
├── supabase/
│   └── functions/          # Edge functions
│       ├── relayer-deposit-polygon/
│       ├── relayer-claim/
│       └── relayer-refund-polygon/
└── README.md

---

How to Use BlokPay

BlokPay makes it easy to send money from anywhere to Nigeria. Here's a complete guide:

Getting Started (Non-Crypto Users Welcome!)

Step 1: Connect Your Wallet

1. Visit blokpay.vercel.app
2. Click "Get Started" or "Send Money"
3. Choose how to connect:
   • Email (easiest for non-crypto users) - Enter your email address
   • Phone Number - Enter your mobile number
   • Google/Apple - Sign in with your Google or Apple account
   • External Wallet - Connect MetaMask, Coinbase Wallet, or Rainbow

Tip: If you're new to crypto, we recommend starting with Email - we'll create an embedded wallet for you automatically!

Step 2: Get Test USDC (For Testing)

Before sending real money, you can test with free test tokens on Base Sepolia:

1. Get Your Wallet Address:

   • After connecting, go to the Receive page
   • Copy your wallet address (starts with 0x...)

2. Get Free Test USDC:

   • Visit: https://faucet.circle.com/
   • Select Base (Sepolia) network
   • Paste your wallet address
   • Click Request USDC
   • Wait a few minutes for the tokens to arrive

3. Verify:

   • Your balance should show in the dashboard
   • You now have test USDC to try the app!

Step 3: Send Money to Nigeria

Option A: Send to Bank Account (Recommended)

This sends NGN directly to a Nigerian bank account:

1. Enter the amount in USDC you want to send
2. View the NGN conversion and fee breakdown
3. Select "Send to Bank Account"
4. Choose the Nigerian bank from the dropdown
5. Enter the recipient's account number
6. Click "Verify Recipient" - we'll confirm the account name
7. Confirm: "Yes, this is correct"
8. Click "Deposit & Send"
9. Wait for on-chain confirmation (~10-15 seconds)
10. Done! NGN is sent instantly to the bank account

Option B: Send Directly to Wallet

Send USDC directly to another crypto wallet:

1. Toggle to "Send to Wallet Address"
2. Enter the recipient's wallet address
3. Select the network (Base or Polygon)
4. Click "Send Direct"

---

Important Notes

For Testnet (Base Sepolia)

• Uses CDP Paymaster for gasless transactions (no ETH needed for gas)
• Test USDC from: https://faucet.circle.com/

For Production

• Gas fees may apply
• You'll need real USDC on Polygon or Base mainnet

Approval Required

On first deposit, you may need to approve USDC spending:

• Your wallet will prompt you to approve the escrow contract
• This is a one-time setup per wallet
• After approval, subsequent deposits are instant

---

Receiving Money

Recipients don't need to do anything!

When you send to a bank account:

• The money goes directly to the bank account number you entered
• The recipient receives NGN instantly
• No claim codes or wallet needed!

---

Frequently Asked Questions

Do I need crypto experience?

No! You can sign up with just an email. We handle all the crypto complexity.

What fees does BlokPay charge?

• Platform fee: 1.5% (vs 5-7% at Western Union)
• Network fees: Minimal (covered by gasless transactions on Base)

Is it safe?

• USDC is held in a secure escrow smart contract
• Bank account verification prevents fraud
• All transactions are on-chain and traceable

How long does it take?

• On-chain deposit: ~10-15 seconds
• Bank payout: Instant (within seconds via Interswitch)

---

Hackathon Information

• Event: Enyata Buildathon 2026
• Sector: Cross-Border Payments + Blockchain
• Development Period: March 23–26, 2026
• Demo Day: April 11 at Interswitch HQ Lagos
• Built with: Interswitch Transfers API (mandatory integration)

License

MIT License - see LICENSE file for details.