FlareHQ SDKs for Node.js, React, and Python

FlareHQ provides three official client libraries so you can integrate USDC payments, escrow, streaming, and x402 access control into any stack — from TypeScript backends and Next.js frontends to Python microservices and AI agents. Choose the SDK that matches your environment, or combine them when you need both a server-side API client and embeddable UI components.

Installation

Node.js / TypeScript
React
Python

The @flarehq/sdk package is the primary SDK and the most feature-complete client. It targets Node.js 18+ and has full TypeScript typings.

npm install @flarehq/sdk viem

pnpm add @flarehq/sdk viem

yarn add @flarehq/sdk viem

bun add @flarehq/sdk viem

The @flarehq/react package wraps the core Node.js SDK and exports pre-built UI components — checkout buttons, payment link displays, and stream status widgets — ready to drop into any React or Next.js app.

npm

npm install @flarehq/react

The flarehq-python package targets Python 3.9+ and exposes the same primitives as the Node.js SDK through an idiomatic, synchronous-by-default interface.

pip

pip install flarehq-python

Node.js / TypeScript SDK

The Node.js SDK is the recommended choice for server-side logic: creating checkout sessions, managing escrows, verifying webhooks, and deploying AI agents. Initialize a single shared client in your project and import it wherever you need it.

src/lib/flarehq.ts

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

export const flarehq = new FlareHQ({
  apiKey: process.env.FLAREHQ_SECRET_KEY!,
  environment: 'testnet', // or 'production'
  chain: {
    id: 5042002,
    rpcUrl: process.env.ARC_RPC_URL,
  },
});

Store your secret key only in server-side environment variables — never expose fhq_sec_... keys to the browser. Use your Publishable Key (fhq_pub_...) for any client-side initialization.

Create a checkout session

Once the client is initialized, creating a hosted checkout session is a single async call:

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: '10.00',
    currency: 'USDC',
    recipient: '0x3500000000000000000000000000000000008004',
    description: 'FlareHQ Pro Subscription',
    successUrl: 'https://yourdomain.com/success',
    cancelUrl: 'https://yourdomain.com/cancel',
    metadata: { customerUsername: '@alex' },
  });

  return NextResponse.json({ url: session.url });
}

React SDK

The React SDK builds on top of @flarehq/sdk to give you ready-made components for embedding payment flows directly in your UI. It handles loading states, error feedback, and wallet connection out of the box — so you can ship a checkout experience without building one from scratch.

src/components/CheckoutButton.tsx

import { FlareCheckout } from '@flarehq/react';

export function CheckoutButton() {
  return (
    <FlareCheckout
      publishableKey={process.env.NEXT_PUBLIC_FLAREHQ_PUBLISHABLE_KEY!}
      amount="10.00"
      currency="USDC"
      recipient="0x3500000000000000000000000000000000008004"
      onSuccess={(event) => console.log('Paid:', event.data.id)}
      onError={(err) => console.error(err)}
    />
  );
}

The React SDK requires @flarehq/sdk as a peer dependency. If you are already using the Node.js SDK in the same project, no additional installation is needed.

Python SDK

Use flarehq-python for Python backends, data pipelines, and autonomous agents that need to create payment sessions, release escrows, or listen for on-chain events.

src/payments/checkout.py

import os
from flarehq import FlareHQ

client = FlareHQ(
    api_key=os.environ['FLAREHQ_SECRET_KEY'],
    environment='testnet',  # or 'production'
)

session = client.checkout.create_session(
    amount='10.00',
    currency='USDC',
    recipient='0x3500000000000000000000000000000000008004',
    description='FlareHQ Pro Subscription',
    success_url='https://yourdomain.com/success',
    cancel_url='https://yourdomain.com/cancel',
)

print(session.url)

SDK Capability Overview

Not every SDK surfaces every feature. Use this table to confirm the right library for your use case:

Feature	Node.js SDK	React SDK	Python SDK
Checkout Sessions	✓	✓	✓
Payment Links	✓	✓	✓
Streaming Payments	✓	—	✓
Escrow	✓	—	✓
x402 Middleware	✓	—	—
Agent Deployment	✓	—	✓
Webhooks	✓	—	✓

The React SDK is intentionally scoped to UI rendering. Server-side operations — escrow, streaming, webhooks, and x402 — must be handled from your backend using the Node.js or Python SDK.

Keeping Your SDKs Up to Date

FlareHQ ships updates to all three SDKs as new Arc testnet features become available. Run the following commands to pull the latest versions:

npm update @flarehq/sdk @flarehq/react

pnpm update @flarehq/sdk @flarehq/react

pip install --upgrade flarehq-python

Breaking changes are signalled by a major version bump. Review the changelog before upgrading across a major version in production.

Next Steps

Webhooks

Receive real-time HTTP notifications for payment, escrow, and stream events.

Errors & Troubleshooting

Understand HTTP status codes and resolve common integration issues.

Hosted Checkout

Build a complete USDC checkout flow with the pre-built payment page.

Quickstart

Go from zero to your first on-chain payment in under five minutes.

Get Started

Payments

x402 Protocol

Agentic Finance

Developer Guide

FlareHQ SDKs for Node.js, React, and Python

Installation

Node.js / TypeScript SDK

Create a checkout session

React SDK

Python SDK

SDK Capability Overview

Keeping Your SDKs Up to Date

Next Steps

Webhooks

Errors & Troubleshooting

Hosted Checkout

Quickstart

​Installation

​Node.js / TypeScript SDK

​Create a checkout session

​React SDK

​Python SDK

​SDK Capability Overview

​Keeping Your SDKs Up to Date

​Next Steps

Webhooks

Errors & Troubleshooting

Hosted Checkout

Quickstart

Installation

Node.js / TypeScript SDK

Create a checkout session

React SDK

Python SDK

SDK Capability Overview

Keeping Your SDKs Up to Date

Next Steps