FlareHQ Quickstart: Send Your First USDC Payment in Minutes

This guide walks you from zero to a working USDC payment on Arc Mainnet. By the end you’ll have the SDK installed, a live checkout session URL in your terminal, and a webhook handler ready to receive payment confirmations. Production payments settle in real USDC on Arc Mainnet (chain ID 5042).

Networks: Production = Arc Mainnet (chain ID 5042, RPC https://rpc.mainnet.arc.io, explorer https://explorer.arc.io). Development/test = Arc Testnet (chain ID 5042002, RPC https://rpc.testnet.arc.network, explorer https://testnet.arcscan.app, test USDC from faucet.circle.com). Default to Mainnet unless you are explicitly developing against testnet.

Prerequisites: Node.js 18+ or Bun, a flarehq.xyz account, and a project directory ready for a new dependency. The SDK is framework-agnostic but the examples below use Next.js API routes.

Create your FlareHQ account

Head to flarehq.xyz and sign up with your business email. You’ll receive a 6-digit verification code — enter it on the confirmation screen to activate your account.Once verified, complete the merchant onboarding form:

Business name — displayed on hosted checkout pages
Payout wallet — choose a Circle MPC wallet (provisioned automatically) or bring your own external address

Your dashboard opens as soon as onboarding is complete. Keep this tab open for the next step.

The Circle MPC option is the fastest path to get started. Your wallet is provisioned instantly and you don’t need to manage private keys yourself.

Generate your API keys

In the FlareHQ dashboard, navigate to Settings > API Keys at flarehq.xyz/developer.Click Generate new key to create an API key:

API Key (arc_live_...) — for server-side SDK calls and direct API requests. Pass it as the x-api-key header. Never expose this in the browser.

Copy the key and add it to your project’s .env.local file along with the Arc Mainnet connection details:

.env.local

FLAREHQ_SECRET_KEY="arc_live_..."
ARC_RPC_URL="https://rpc.mainnet.arc.io"
CHAIN_ID="5042"

For Arc Testnet development only, use ARC_RPC_URL="https://rpc.testnet.arc.network" and CHAIN_ID="5042002" with test USDC from faucet.circle.com.

Your API key is shown only once at generation time — the same one-time display behaviour as the key issued by POST /api/merchant/verify. Store it immediately in a password manager or secrets vault — you cannot retrieve it again from the dashboard. If you lose it, revoke the key and generate a new one.

Install the SDK

Add the FlareHQ SDK and viem (the Arc client library) to your project:

npm install @flarehq/sdk viem

pnpm add @flarehq/sdk viem

yarn add @flarehq/sdk viem

bun add @flarehq/sdk viem

The @flarehq/sdk package ships full TypeScript types, so you get autocomplete and inline documentation in any TypeScript or JavaScript project.

Initialize the FlareHQ client

Create a shared client instance that you can import wherever you need to interact with the FlareHQ API. A dedicated module keeps your configuration in one place and makes testing straightforward.

src/lib/flarehq.ts

import { FlareHQ } from '@flarehq/sdk';

export const flarehq = new FlareHQ({
  apiKey: process.env.FLAREHQ_SECRET_KEY!,
  environment: 'production',      // Use 'testnet' only for Arc Testnet development
  chain: {
    id: 5042,               // Arc Mainnet chain ID (testnet: 5042002)
    rpcUrl: process.env.ARC_RPC_URL,
  },
});

Import flarehq from this module in your route handlers and server-side functions. Never import it in client components — the secret key must stay server-side only.

Create your first checkout session

Call POST /api/payments/initialize (or the equivalent SDK method) to create a payment session. The response includes a checkoutUrl you can redirect customers to or embed as a link.

// src/app/api/checkout/route.ts
import { NextResponse } from 'next/server';
import { flarehq } from '@/lib/flarehq';

export async function POST() {
  const session = await flarehq.checkout.createSession({
    amount: '25.00',                        // Amount in USDC
    currency: 'USDC',
    description: 'Pro plan — monthly',
    successUrl: 'https://yourdomain.com/success',
    cancelUrl: 'https://yourdomain.com/cancel',
    metadata: {
      customerId: 'cus_abc123',
    },
  });

  // session.checkoutUrl → https://flarehq.xyz/checkout/{reference}
  return NextResponse.json({ url: session.checkoutUrl });
}

curl -X POST https://flarehq.xyz/api/payments/initialize \
  -H "x-api-key: arc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.00",
    "currency": "USDC",
    "webhookUrl": "https://yourdomain.com/api/webhooks"
  }'

A successful response looks like this:

{
  "success": true,
  "reference": "arc_ref_k7x2mq9p1z3",
  "checkoutUrl": "https://flarehq.xyz/checkout/arc_ref_k7x2mq9p1z3",
  "data": {
    "reference": "arc_ref_k7x2mq9p1z3",
    "amount": "25.00",
    "currency": "USDC",
    "status": "ready"
  }
}

Redirect your customer to checkoutUrl. FlareHQ handles the payment UI, wallet connection, and on-chain settlement. The session expires after 120 minutes if no payment is made.

Set up webhooks

FlareHQ sends POST requests to the webhookUrl you attached at initialization when payment events occur.

Outbound webhook deliveries are currently unsigned and fire-and-forget (no retries). Always re-verify the payment server-side with GET /api/payments/verify/{reference} before fulfilling the order — see Webhooks for details.

src/app/api/webhooks/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { flarehq } from '@/lib/flarehq';

export async function POST(req: NextRequest) {
  const payload = await req.text();
  const signature = req.headers.get('x-flarehq-signature')!;

  let event;
  try {
    // constructEvent throws if the signature is invalid
    event = flarehq.webhooks.constructEvent(
      payload,
      signature,
      process.env.FLAREHQ_WEBHOOK_SECRET!
    );
  } catch (err) {
    return NextResponse.json(
      { error: 'Webhook signature verification failed' },
      { status: 400 }
    );
  }

  switch (event.type) {
    case 'payment.settled':
      // Fulfil the order, unlock access, send a receipt, etc.
      console.log('Payment settled:', event.data.reference, event.data.amount, 'USDC');
      break;

    case 'escrow.created':
      console.log('Escrow opened:', event.data.reference);
      break;

    case 'escrow.disputed':
      console.log('Dispute raised:', event.data.reference);
      break;
  }

  return NextResponse.json({ received: true });
}

Register your webhook URL in the dashboard under Settings > Webhooks. FlareHQ will generate a FLAREHQ_WEBHOOK_SECRET for you — add it to your environment variables.

Always verify the x-flarehq-signature header before acting on a webhook. Skipping verification leaves your endpoint open to spoofed events.

Next steps

You’ve got the foundations in place. Here are the most common directions to explore next:

Hosted Checkout

Customise the checkout page with your logo, colours, and success redirect behaviour.

x402 Micro-Paywalls

Gate an API endpoint and charge AI agents or third-party clients per request.

Streaming Payments

Set up a per-second USDC stream to a contractor, subscription, or DAO treasury.

Escrow & Disputes

Hold funds in a milestone-gated contract with on-chain dispute resolution.

Get Started

Payments

x402 Protocol

Agentic Finance

Merchant Platform

Consumer Payments

Developer Guide

FlareHQ Quickstart: Send Your First USDC Payment in Minutes

Next steps

Hosted Checkout

x402 Micro-Paywalls

Streaming Payments

Escrow & Disputes

​Next steps

Hosted Checkout

x402 Micro-Paywalls

Streaming Payments

Escrow & Disputes

Next steps