API Documentation

Access Belong’s public API to build, integrate, or automate token-gated experiences.
Our latest version includes OpenAPI documentation, REST endpoints, and developer-friendly responses.

Production Environment

Belong’s production stack powers the live customer experience. You’ll see Belong in domains like checkin.belong.net and belong.net.

Use this tier for all integrations, launch prep, and real user data.

Getting an API Key

Generate API keys from the Belong CheckIn dashboard:

• checkin.belong.net

Using the x-api-key Header

For protected routes, include your API key in the request headers as x-api-key.

const response = await fetch('https://api.belong.net/api/v3/events', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<your-api-key>',
  },
});

const data = await response.json();
console.log(data);

API Versions

Belong API v3

Use our OpenAPI explorers to browse, test, and integrate faster than ever.

Belong API v2 (Deprecated)

Fully deprecated. Use v3 for all integrations.

Belong API v1 (Legacy)

Fully deprecated.

Getting Started

1. Explore the docs
   Open API interactive Docs
2. Authenticate if needed
   Use x-api-key: <token> for protected routes.
3. Test requests in browser
   Use the interactive API explorer to run and debug calls directly.
4. Start building
   Fetch events, manage addresses, and mint collections via simple REST endpoints.

Example Use Cases

• Create token-gated events
  → POST /events — Add event with NFT access & visibility rules.
• Autocomplete address input
  → GET /adresses/autocomplete?q=Burning — Get venue suggestions with coordinates.
• Publish Sui NFT collections
  → POST /crypto/sui/collection/publish — Create access tokens for events.
• Run sponsored gas flows with Belong ledger accounting
  → GET/POST /sponsorship/* — Track deposits, balances, settings, and eligibility checks for sponsored EVM flows.
• Accept store payment and issue an NFT → POST /checkout/sessions — Create a hosted, server-owned NFT checkout for an external order.

NFT Checkout API

The NFT Checkout API lets a Shopify or custom store keep its own products and orders while Belong handles crypto payment and NFT issuance.

Key routes:

• POST /api/v3/checkout/sessions — create or replay an idempotent checkout session; requires checkout:create API-key permission.
• GET /api/v3/checkout/sessions/:checkoutId — read the client-safe hosted session using X-Checkout-Client-Secret.
• POST /api/v3/checkout/sessions/:checkoutId/webhook/retry — retry the signed completion webhook; requires checkout:retry API-key permission.

The server API key and webhook signing secret must stay on the store backend. For the full flow, payloads, SDK embed, top-up behavior, and webhook verification, see NFT Checkout.

Sponsorship API

Belong API v3 now includes sponsorship ledger endpoints for sponsored on-chain flows such as CheckIn, NFT mint, and future membership flows. For CheckIn promoter reward withdrawals, the same ledger can also authorize a backend-submitted distribute_promoter_payments transaction when the venue sponsor has explicitly enabled that operation type.

Key routes:

• GET /api/v3/sponsorship/balance?walletAddress=0x...&chainId=...
• GET /api/v3/sponsorship/usage?walletAddress=0x...&chainId=...
• GET /api/v3/sponsorship/deposits?walletAddress=0x...&chainId=...
• GET /api/v3/sponsorship/settings?walletAddress=0x...&chainId=...
• POST /api/v3/sponsorship/settings
• POST /api/v3/sponsorship/check
• POST /api/v3/sponsorship/thirdweb/verify
• POST /api/v3/sponsorship/thirdweb/complete
• POST /api/v3/sponsorship/thirdweb/cancel
• POST /api/v3/sponsorship/deposits/record
• POST /api/v3/sponsorship/usage/record
• POST /api/v3/crypto/evm/venue-gasless
• POST /api/v3/nft-collection/:id/gasless

Authentication summary:

• balance, usage, deposits, settings, check, thirdweb/complete, and thirdweb/cancel require the authenticated owner/session.
• thirdweb/verify is called by thirdweb and requires x-belong-thirdweb-verifier-secret.
• check, deposits/record, and usage/record are rate-limited to reduce reservation, RPC lookup, and ledger-write abuse.
• deposits/record is integrity-protected by on-chain verification and does not move funds.
• usage/record requires a server-side Belong API key with sponsorship:write ({ "sponsorship": ["write"] }).
• Browser thirdweb flows must follow check -> thirdweb sponsored tx with verifier -> thirdweb/complete when a transaction is broadcast or has a receipt. Use thirdweb/cancel only for thirdweb pre-broadcast denials with no txHash.
• thirdweb/complete must include the same clientId, targetAddress, callData, and nativeValueWei that were verified before sponsorship. For direct EOA and EIP-7702, usage is recorded against the EOA actorAddress or ownerAddress; EIP-7702 completion verifies the delegated EOA execution account and wrapped thirdweb call. For ERC-4337, include smartAccountAddress.
• thirdweb/cancel does not accept sponsorAddress, txHash, or receipt data; it resolves the sponsor server-side and releases only a matching active reservation.
• For ERC-4337 account-abstraction transactions, thirdweb/complete also verifies entryPointAddress and the on-chain UserOperationEvent.
• Do not expose usage/record to browsers or clients; it is only for trusted server integrations.

For the full flow, examples, and payloads, see Sponsored Gas Ledger Guide.