Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flow402.net/llms.txt

Use this file to discover all available pages before exploring further.

​
Create your project

Initialize a new express project.

​
Server-side

Follow the steps below to setup your server.
1

Create your api project

shell
mkdir my-express-project
cd my-express-project
npm init -y
npm install express axios
2

Setup Express

main.js
const express = require('express')
const axios = require('axios')

const app = express()
app.use(express.json())

// MIDDLEWARES

// ENDPOINTS

app.listen(8000)
3

Add middleware

main.js
// MIDDLEWARES
async function settleWithFlow402({ nonce, txHash, feeTxHash, intentId }) {
    const url = "https://api.flow402.net/settle"

    const payload = {
        nonce,
        txHash,
        feeTxHash,
        intentId
    }

    const res = await axios.post(url, payload, {
        headers: { 'Content-Type': 'application/json' }
    })

    return res.data
}

async function requirePayment(req, res, next) {
    const nonce = req.body["nonce"]
    const intentId = req.body["intentId"]
    const txHash = req.body["txHash"]
    const feeTxHash = req.body["feeTxHash"] || null

    // Return 402 status code "Payment required"
    if (!nonce || !intentId || !txHash) {
        return res.status(402).json({
            error: 'payment_required',
            message: 'Missing Flow402 payment body.',
            expectedBody: [
                "nonce",
                "intentId",
                "txHash"
            ],
            optionalBody: "feeTxHash"
        })
    }

    const result = await settleWithFlow402({
        nonce,
        txHash,
        feeTxHash,
        intentId
    })

    // Return 402 status code "Payment required"
    if (!result.settled) {
        return res.status(402).json({
            error: 'payment_not_settled',
            message: 'Payment not settled on-chain.',
            facilitatorResponse: result
        })
    }

    // Attach receipt to request to be handled
    req.flow402 = {
        txHash: result.txHash,
        receipt: result.receipt
    }

    return next()
}
4

Create your endpoints

main.js
// ENDPOINTS

// Free/public endpoint
app.get('/api/free', (req, res) => {
    res.json({
        status: 'ok',
        type: 'free',
        message: 'This is a free endpoint. No payment required.'
    })
})

// Premium endpoint protected with Flow402
app.get('/api/premium', requirePayment, (req, res) => {
    const paymentInfo = req.flow402

    res.json({
        status: 'ok',
        type: 'premium',
        message: 'Welcome to the premium API',
        payment: paymentInfo
    })
})

​
Client-side

Follow the steps below to request Flow402 protocol from your shell.
1

Call /verify endpoint

shell
curl -s -X POST \
-H "Content-Type: application/json" \
-d '{
    "from": "0xPAYER",
    "to": "0xMERCHANT",
    "amount": "0.10",
    "network": "base",
    "scheme": "exact"
}' \
https://api.flow402/verify
2

Send two transactions using USDC and Base network

Use any wallet to send a transaction from PAYER address to your MERCHANT address.Also send a transaction from PAYER address to our FACILITATOR address 0xc4a35c792a020d55218b83c5d77172b86b934dce. This transaction’s amount needs to be greater than 0.001 USDC and greater than AMOUNT*0.1 (1% tax fee).
3

Call your paid api endpoint

shell
curl -s -X POST \
-H "Content-Type: application/json" \
-d '{
    "nonce": "nonce-given-from-first-request",
    "intentId": "intentId-given-from-first-request",
    "txHash": "transaction-hash-from-payer-to-merchant",
    "feeTxHash": "transaction-hash-from-payer-to-facilitator",
}' \
http://localhost:8000/api/premium
Response:
json
{
    "status": "ok",
    "type": "premium",
    "message": "Welcome to the premium API 🚀",
    "payment": {
        "txHash": "0xMERCHANT_TX_HASH",
        "receipt": {
            "intentId": "pi_...",
            "amount": "0.10",
            "currency": "USDC",
            "network": "base",
            "merchant": "0xYOUR_MERCHANT_ADDRESS",
            "facilitatorRecipient": "0xc4a35c792a020d55218b83c5d77172b86b934dce",
            "fee": "0.001",
            "feeTxHash": "0xFEE_TX_HASH"
        }
    }
}