Getting Started

Coinbax builds payment controls for programmable money. The Payments API wraps every transaction in the Coinbax Execution Framework (Verify, Fund, Confirm, Settle), so escrow, compliance screening, and approval rules run on every payment you create.

This guide takes you from a new account to your first escrowed USDC payment on Base Sepolia, the staging testnet.

1. Create an account

Sign up at beta.coinbax.com/signup. Your account gets a workspace: the tenant that owns your customers, transactions, templates, and credentials.

Verify your email before continuing. Staging access is approved for developer testing; production access is a separate conversation with our team.

2. Get staging API credentials

In the dashboard, switch to the staging environment and open your workspace settings to obtain an API key. Staging keys only work against staging, and staging only ever touches testnets. The two environments are enforced at the infrastructure level: a staging deployment refuses to start if it is configured with mainnet networks.

Keys are shown once at creation. Store yours immediately; it cannot be retrieved later.

export COINBAX_API_KEY=cbx_...

All Payments API requests authenticate with the X-API-Key header. See the authentication guide for OAuth 2.0 client credentials, the alternative for service-to-service integrations.

3. Know your staging constants

Need testnet USDC? Use the Circle faucet and select Base Sepolia. Testnet ETH for gas comes from any Base Sepolia faucet.

4. Create your customers

Transactions move funds between customers of your workspace. Create a sender and a receiver:

curl -X POST https://api-staging.coinbax.com/api/v1/customers \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sender@example.com",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2",
    "blockchainNetwork": "base"
  }'

Repeat for the receiver. The response envelope is the same on every endpoint:

{
  "success": true,
  "data": { "id": "...", "status": "active" },
  "meta": { "timestamp": "...", "requestId": "..." },
  "error": null
}

If your workspace requires customer approval, new customers start in pending until approved in the dashboard.

5. Create your first transaction

curl -X POST https://api-staging.coinbax.com/api/v1/transactions \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2",
    "toAddress":   "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "amount": 100,
    "currency": "USDC",
    "blockchainNetwork": "base",
    "orchestrationType": "coinbax",
    "templateId": "<your-template-id>"
  }'

orchestrationType: "coinbax" routes the payment through programmable escrow with the controls defined on your template. The response returns the transaction in PENDING; compliance screening and risk scoring run before any funds move.

Follow the transaction through the lifecycle with:

curl https://api-staging.coinbax.com/api/v1/transactions/<transactionId> \
  -H "X-API-Key: $COINBAX_API_KEY"

See your first transaction for the full walkthrough of each state.

6. Subscribe to webhooks (recommended)

Rather than polling, register a webhook and receive every state transition:

curl -X POST https://api-staging.coinbax.com/api/v1/webhooks \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/coinbax-webhook",
    "eventTypes": ["transaction.created", "transaction.escrowed", "transaction.completed"]
  }'

Delivery is retried with circuit-breaker protection. See the webhooks guide for event types and signature verification.

Next steps

• Your first transaction: the full lifecycle walkthrough
• The Coinbax Execution Framework: how Verify, Fund, Confirm, Settle work
• API scopes: what your key can and cannot do
• Payments API reference: every endpoint, with runnable samples

Building with an AI agent? This entire site is machine-readable: see llms.txt, append .md to any page URL for raw markdown, or connect to the MCP server.