Quickstart

Somebody told you to integrate with ChatterPay. This page takes you from that sentence to a first transfer you can watch settle, and defines every word it uses before it uses it. You need no access to our code and no prior knowledge of our architecture.

What is ChatterPay?

ChatterPay B2B is WhatsApp infrastructure for blockchain operations, integrated backend to backend. Your backend holds a credential, calls the API, and the platform provisions the wallets, moves the funds across blockchain networks and reports what happened.

What you get out of it: a wallet for each of your users, addresses they can receive money at, balances you can read, a price for a transfer before you commit to it, and a durable record of every operation that tells you how it ended.

What the platform operates on your behalf: a node or RPC relationship per network, the fee and gas mechanics of each one, and the retry and reconciliation machinery behind a payment that takes minutes to settle. Signing stays partner-managed: the keys stay in your environment and the platform asks your signer for each signature.

What do I integrate?

Three public surfaces, and you can use as many of them as you need:

• The official SDK — @chatterpay/sdk, a typed TypeScript client over the same operations. Optional, and the fastest route.
• The REST API — the API Reference is the contract. Any backend that can make an HTTPS request is a first-class consumer; nothing is reachable only through the SDK.
• Webhooks — signed HTTP notifications the platform sends to an endpoint you register, so you learn how an operation ended without polling. You can also read the same facts in order from the events cursor.

Install the SDK

bun add @chatterpay/sdk
# or: npm install @chatterpay/sdk

The package is published publicly as @chatterpay/sdk. You need no access to any ChatterPay repository to integrate.

Authenticate

You receive three things at onboarding: the base URL of the deployment you were assigned, a client id, and the credential that proves it is you.

The API is protected by OAuth 2.0 Client Credentials. Your backend exchanges its credential for a short-lived access token and sends that token as a bearer token on every call.

• A productive integration authenticates with private_key_jwt: you sign a short assertion with a key whose public half was registered for your client, and the private half never leaves you.
• A client secret is the grant permitted for Sandbox only.

import { ChatterPayClient } from "@chatterpay/sdk";

const client = await ChatterPayClient.connect({
  baseUrl: process.env.CHATTERPAY_API_URL,
  clientId: process.env.CHATTERPAY_CLIENT_ID,
  clientSecret: process.env.CHATTERPAY_CLIENT_SECRET,
});

Identify your customer

A tenant is the box your data lives in: one unit of administrative and data isolation inside a deployment. Yours is derived from the credential that authenticated the request. It is not a parameter you send, and no body, query string or header can reach another tenant's data.

Inside your tenant you register each of your own end users, with your own identifier for them. From then on you address that person by the identifier the platform returned, and the platform relates every wallet and every operation to them.

Create a wallet, and its accounts

Two levels, and the difference matters:

• A wallet is the user's holding in ChatterPay. It is the thing you create per user.
• A chain account is that wallet's account on one specific blockchain network, with that network's own address. One wallet holds one chain account per network enabled for your deployment.

You create the wallet once, then provision a chain account on each network you intend to use. Which networks are available to you is a property of your deployment; the Roadmap is the public view of what is available, in development and planned.

Receive money

A deposit route is the address — plus any memo or tag the network requires — that funds can be sent to from outside the platform in order to be credited to a user's wallet. You ask for the deposit route of a wallet on a network and show it to your user.

When money arrives, the platform observes it, credits the wallet and reports it like any other operation. In Sandbox you can also credit a test wallet from a faucet instead of waiting for a real deposit.

Reading what a user holds is a separate call, and it answers per network and per asset.

Price it: the quote

A quote is a priced estimate of an operation before it is executed. It states the route the money would take, any asset conversion involved, each fee separately — the ChatterPay service fee, any provider fee, the network fee — and the total debit, which is the one number that leaves the user's balance.

Every amount in a quote is in base units: the asset's smallest indivisible unit, as an integer. One USDC with six decimals is 1000000. Nothing is ever rounded into or out of a decimal.

A quote expires. A route whose total debit cannot be determined safely is not offered as executable rather than being offered with a guess.

Execute it

You accept a quote to turn the intent into an operation, and you send a unique request id with it. That id is what makes the call safe to retry: sending it again returns the original operation instead of creating a second payment. Every financial mutation requires one.

const quote = await client.quote({ /* who sends, who receives, asset, amount */ });
const operation = await client.transfer({
  quoteId: quote.quoteId,
  requestId: crypto.randomUUID(),
});

Follow the operation

An operation is the durable resource that represents the transfer. It is created immediately and settles asynchronously, because a blockchain takes as long as it takes.

It carries its own timeline: the steps it went through, and — when a single payment travelled as more than one transaction — a leg per transaction, each with its own network, amount, hash and status. On an EVM network it also carries userOpHash, the identifier a bundler and the EntryPoint know the submission by, next to transactionHash.

You read an operation by its id whenever you want, and its final state is also delivered to you (see below). Operations, quotes and states describes every state and what it guarantees.

Be told, instead of asking

Register an endpoint and the platform sends you a signed HTTP notification when an operation changes state. Verify the signature before you act on the body — that is what distinguishes a notification from this platform from a request from anybody. Webhooks and channels carries the signature scheme, the retry behaviour and what a delivery failure does.

If your receiver was down, the events cursor is the catch-up path: read forward from the last position you processed and nothing is missed.

What runs where

Responsibilities states the split in full, and Environments and profiles states what a Sandbox result does and does not promise about production.

Try it without integrating anything

The Sandbox runs these flows in your browser and shows you the resulting operation timeline, so you can see the shape of a transfer before you write a line of code. No sandbox or testnet result is a commitment about a production deployment.