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 OAuth credentials

In the dashboard, switch to the staging environment and open your workspace settings to create an OAuth client. Staging credentials 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.

The client secret is shown once at creation. Store it immediately; it cannot be retrieved later.

export COINBAX_CLIENT_ID=coinbax_client_...
export COINBAX_CLIENT_SECRET=...

Exchange them for a short lived access token, and send that token on every Payments API request:

export ACCESS_TOKEN=$(curl -s -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$COINBAX_CLIENT_ID\",\"client_secret\":\"$COINBAX_CLIENT_SECRET\"}" \
  | jq -r .data.access_token)

The token endpoint uses RFC 6749’s snake_case field names, unlike the rest of the API. It expires in an hour (expires_in), so request a fresh one rather than caching it indefinitely.

The Payments API v2 accepts OAuth 2.0 Bearer tokens only. API keys work against /api/v1, which sunsets on 1 November 2026 — see the authentication guide.

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. Customers are optional

A transaction moves funds between two wallet addresses, so you do not need to create customer records to make your first payment. Customer records are a Workspace API concept (/workspaces/{id}/customers on the Workspace API), managed by workspace admins, and used when you want to associate a payment with a known party. If you have one, pass its id as customerId on the transaction. Otherwise, skip straight to creating a transaction with addresses.

Every endpoint returns the same envelope:

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

5. Create your first transaction

curl -X POST https://api-staging.coinbax.com/api/v2/transactions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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/v2/transactions/<transactionId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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:

Webhook subscriptions live on the Workspace API, alongside the rest of workspace configuration:

curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/$WORKSPACE_ID/webhooks \
  -H "Authorization: Bearer $WORKSPACE_JWT" \
  -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.