Docs
GitHubDiscord

API Quickstart

Create a connected account, onboard a seller, and send their first USDC payout.

This guide uses the Zoneless Node.js SDK and Zoneless Cloud in live mode. Prefer the dashboard? Follow the dashboard quickstart. If you self-host, complete Self-hosting first and replace the cloud API URL with your instance URL.

1Get your API key

Create a Zoneless account, then copy your live secret key from the dashboard. It starts with sk_live_z_. Store it in an environment variable and only use it in server-side code. See Authentication for test mode and self-hosted keys.

2Install the SDK

Install the Zoneless Node.js SDK using your preferred package manager.

Install
npm install @zoneless/node

3Initialize the client

Create one Zoneless client and reuse it for the requests below.

Initialize the client
import { Zoneless } from '@zoneless/node';

const apiKey = process.env.ZONELESS_API_KEY;
const apiUrl = process.env.ZONELESS_API_URL;

if (!apiKey || !apiUrl) {
  throw new Error('Missing Zoneless configuration');
}

const zoneless = new Zoneless(apiKey, apiUrl);

4Create a connected account

Create an Express connected account for the seller. Save the account ID in your database so you can use it for onboarding, transfers, payouts, and later API requests.

This example requests the transfers capability because the account will receive funds from your platform.

Create account
const account = await zoneless.accounts.create({
  type: 'express',
  country: 'US',
  email: 'seller@example.com',
  capabilities: {
    transfers: { requested: true },
  },
});

console.log(account.id); // acct_z_1234...

Create an Account Link and redirect the seller to its url. They will add their details and connect the Solana wallet where they want to receive payouts.

Create account link
const accountLink = await zoneless.accountLinks.create({
  account: account.id,
  refresh_url: 'https://yoursite.com/reauth',
  return_url: 'https://yoursite.com/return',
  type: 'account_onboarding',
});

// Redirect the seller to accountLink.url
console.log(accountLink.url);

6Wait for onboarding to finish

Do not create a payout as soon as the seller reaches your return URL. Retrieve the account and check that payouts_enabled is true. In production, listen for account.updated webhooks instead of polling.

If you require identity verification before a seller can be paid, add the checks in the Identity Verification guide before continuing.

Check account status
const onboardedAccount = await zoneless.accounts.retrieve(
  account.id
);

if (!onboardedAccount.payouts_enabled) {
  throw new Error('Seller has not finished onboarding');
}

7Fund your platform wallet

Your platform wallet must hold enough USDC to cover the transfer and payout. If it is empty, follow Fund your platform wallet before continuing.

8Create a transfer

Create a transfer to credit the connected account's Zoneless balance. This updates the balances recorded by Zoneless, but it does not send USDC to the seller's wallet yet.

Create transfer
const transfer = await zoneless.transfers.create({
  amount: 1, // $0.01
  currency: 'usdc',
  destination: account.id,
  description: 'Payment for services',
});

console.log(transfer.id); // tr_z_1234...

9Create a payout

Create a payout on behalf of the connected account. The zonelessAccount option is the SDK equivalent of the Zoneless-Account request header.

The connected account balance must cover the payout. Creating it reserves the funds and leaves the payout in pending status.

Create payout
const payout = await zoneless.payouts.create({
  amount: 1, // $0.01
  currency: 'usdc',
}, {
  zonelessAccount: account.id,
});

console.log(payout.id); // po_z_1234...

10Process the payout

Creating a payout does not submit a Solana transaction. Call processAll() to build, sign, and broadcast your pending payouts. Once the transaction confirms, the USDC is sent from your platform wallet to each seller's wallet.

processAll() processes every pending payout for the platform. Use processBatch() if you want to process one batch at a time. See Payouts for both helpers and the lower-level signing flow.

Process all payouts
const solanaSecretKey = process.env.SOLANA_SECRET_KEY;

if (!solanaSecretKey) {
  throw new Error('Missing Solana secret key');
}

await zoneless.payouts.processAll(solanaSecretKey);

Next steps