# Coinbax Developers: full documentation corpus

> Generated from the same sources as the HTML site. One section per page,
> each headed by its canonical source URL.

---

# Getting Started

> Go from zero to your first escrowed stablecoin payment on Base Sepolia in a few minutes.
> Source: https://developers.coinbax.com/docs/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](https://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](/docs/api/authentication) for OAuth 2.0 client
credentials, the alternative for service-to-service integrations.

## 3. Know your staging constants

| What | Value |
|---|---|
| Payments API base URL | `https://api-staging.coinbax.com/api/v1` |
| Workspace API base URL | `https://core-staging.coinbax.com/api/v1` |
| Network | Base Sepolia (chain ID `84532`) |
| Test USDC | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |

Need testnet USDC? Use the [Circle faucet](https://faucet.circle.com) 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:

```bash
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:

```json
{
  "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

```bash
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:

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

See [your first transaction](/docs/getting-started/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:

```bash
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](/docs/api/webhooks) for event types and signature
verification.

## Next steps

- [Your first transaction](/docs/getting-started/first-transaction): the full lifecycle walkthrough
- [The Coinbax Execution Framework](/docs/concepts/execution-framework): how Verify, Fund, Confirm, Settle work
- [API scopes](/docs/api/scopes): what your key can and cannot do
- [Payments API reference](/reference/coinbax-api/): every endpoint, with runnable samples

Building with an AI agent? This entire site is machine-readable: see
[llms.txt](/llms.txt), append `.md` to any page URL for raw markdown, or
connect to the [MCP server](/docs/resources/mcp).

---

# Your First Transaction

> Follow one escrowed staging payment through every state of the Coinbax transaction lifecycle, from creation to settlement.
> Source: https://developers.coinbax.com/docs/getting-started/first-transaction

Every Coinbax payment moves through a state machine. This guide creates one
escrowed USDC payment on Base Sepolia and follows it through every state,
with the curl calls and webhook events you will see along the way.

Prerequisites: a staging API key and two customers with wallet addresses.
The [getting started guide](/docs/getting-started/) covers both.

## The lifecycle at a glance

```
PENDING → RISK_REVIEW → ESCROWED → IN_REVIEW → COMPLETED
                            │           │
                            │           ├──▶ REFUNDED
                            │           └──▶ DISPUTED
                            └──▶ (COINBAX: auto-release to COMPLETED)
```

| State | Meaning |
|---|---|
| `pending` | Transaction created, no funds have moved |
| `risk_review` | Compliance screening and risk scoring in progress |
| `pending_user_action` | Waiting on an external wallet to sign and fund the escrow |
| `escrowed` | Funds are locked (in the escrow contract, or transferred for RAW) |
| `in_review` | Review window open; can be approved, refunded, or disputed |
| `disputed` | A dispute is open against the transaction |
| `completed` | Funds released to the receiver (terminal) |
| `refunded` | Funds returned to the sender (terminal) |
| `rescinded` | Sender cancelled during the hold period (terminal) |
| `failed` | A pre-escrow control failed or the blockchain call errored (terminal) |

The API returns states in lowercase in the `status` field. This guide uses
uppercase when talking about states conceptually and lowercase in JSON
samples, matching what the API actually returns.

## Choose an orchestration type

`orchestrationType` decides how funds move:

| | `raw` | `coinbax` |
|---|---|---|
| Mechanism | Direct blockchain transfer | Smart contract escrow |
| Time delay | None | Configurable delay before auto-release |
| Review window | Yes, before completion | No, release is automated |
| Typical flow | PENDING → ESCROWED → IN_REVIEW → COMPLETED | PENDING → ESCROWED → COMPLETED |
| Release | Manual approval or review window expiry | Background job releases after the delay |

**RAW** sends funds directly to the receiver, then holds the transaction in a
review window before marking it complete. **COINBAX** locks funds in an escrow
contract defined by your template; a time-delay control sets a release
timestamp, and Coinbax releases the funds automatically once it passes. Use
COINBAX when you want escrow protection, verification steps, or recourse
before settlement.

## 1. Create the transaction

```bash
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-sepolia",
    "orchestrationType": "coinbax",
    "templateId": "<your-template-id>"
  }'
```

`fromAddress`, `toAddress`, and `amount` are required. `templateId`
references a template from your workspace; the template's
[controls](/docs/concepts/controls) run at fixed points in the lifecycle.

The response arrives in the unified envelope with the transaction in
`pending`:

```json
{
  "success": true,
  "data": {
    "id": "9f8b3c2a-...",
    "status": "pending",
    "orchestrationType": "coinbax",
    "amount": 100,
    "currency": "USDC"
  },
  "meta": { "timestamp": "...", "requestId": "..." },
  "error": null
}
```

Your first webhook fires immediately:

```json
// event: transaction.created
{
  "transaction": { "id": "9f8b3c2a-...", "status": "pending" }
}
```

## 2. PENDING and RISK_REVIEW: the Verify phase

Before any funds move, Coinbax validates the request (addresses, balance,
amount), runs the template's PRE_ESCROW controls (compliance screening,
sanctions checks, SMS verification if configured), and scores the
transaction for risk. This is the Verify phase of the
[Coinbax Execution Framework](/docs/concepts/execution-framework).

Two outcomes:

- Everything passes: the transaction proceeds to escrow.
- A required control fails or the risk score exceeds the threshold: the
  transaction moves to `failed` and a `transaction.failed` webhook fires with
  a `reason`. No funds ever moved.

If the template includes a verification control (2FA, SMS), the transaction
pauses until the code is verified. If the sender funds the escrow from an
external wallet, the transaction sits in `pending_user_action` until the
signed funding transaction lands on-chain.

## 3. ESCROWED: the Fund phase

For `coinbax` transactions, funds lock in the escrow contract and Coinbax
records the on-chain transaction hash. For `raw`, the direct transfer
executes. Check the state at any time:

```bash
curl https://api-staging.coinbax.com/api/v1/transactions/9f8b3c2a-... \
  -H "X-API-Key: $COINBAX_API_KEY"
```

```json
{
  "success": true,
  "data": { "id": "9f8b3c2a-...", "status": "escrowed" },
  "meta": { "timestamp": "...", "requestId": "..." },
  "error": null
}
```

The webhook includes the escrow address and hash:

```json
// event: transaction.escrowed
{
  "transaction": { "id": "9f8b3c2a-...", "status": "escrowed" },
  "escrowAddress": "0x...",
  "txHash": "0x..."
}
```

At this point POST_ESCROW controls run. A TimeDelay control, for example,
sets the release timestamp that the auto-release job will honor.

## 4. IN_REVIEW: the Confirm phase (RAW)

RAW transactions enter a review window (72 hours by default) after the
transfer. During this window the transaction can be approved early,
refunded, or disputed. When the window expires or an approval lands, the
transaction completes.

COINBAX transactions normally skip `in_review`: the escrow auto-releases when
the time delay passes and all PRE_RELEASE controls succeed.

## 5. COMPLETED: the Settle phase

```json
// event: transaction.completed
{
  "transaction": { "id": "9f8b3c2a-...", "status": "completed" },
  "txHash": "0x..."
}
```

`completed` is terminal. The full control execution history and on-chain
references stay on the transaction record as the audit trail.

## The other endings

**Refund.** While funds are escrowed or in review, return them to the sender:

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/9f8b3c2a-.../refund \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer request" }'
```

The transaction moves to `refunded` and a `transaction.refunded` webhook
fires with your reason. Requires the `cancel:transactions` scope.

**Dispute.** Either party can open a dispute against an escrowed or
in-review transaction via `POST /disputes`. The transaction moves to
`disputed` and settlement pauses until the dispute resolves. See the
[Payments API reference](/reference/coinbax-api/) for the dispute endpoints.

**Rescind.** If the template allows it, the sender can cancel during the
hold period via `POST /transactions/{id}/rescind`. The transaction moves to
`rescinded` and a `transaction.rescinded` webhook fires.

## Next steps

- [The Coinbax Execution Framework](/docs/concepts/execution-framework): how the four phases map to these states
- [Payment controls](/docs/concepts/controls): the rules that ran during this lifecycle
- [Webhooks](/docs/api/webhooks): signature verification and retry behavior
- [Payments API reference](/reference/coinbax-api/): every endpoint and field

---

# The Coinbax Execution Framework

> The four-phase payment lifecycle (Verify, Fund, Confirm, Settle) that runs on every Coinbax transaction.
> Source: https://developers.coinbax.com/docs/concepts/execution-framework

Coinbax builds payment controls for programmable money. The Coinbax
Execution Framework is the four-phase lifecycle that every transaction moves
through: **Verify, Fund, Confirm, Settle**. Each phase has a defined job,
runs a defined set of controls, and maps to specific transaction states, so
your integration always knows where a payment is and what can happen next.

```
Verify ──▶ Fund ──▶ Confirm ──▶ Settle
```

## Phase 1: Verify

**States: `PENDING`, `RISK_REVIEW`**

Compliance screening and risk scoring run before funds move. Failed payments
never reach the contract.

What runs here:

- **Request validation.** Addresses, amounts, currency, and network are
  checked against the template and workspace configuration.
- **Compliance screening.** PRE_ESCROW controls execute in order: address
  and sanctions screening, customer screening, amount limits.
- **Risk scoring.** Each transaction is scored on amount, participant
  history, behavior, geography, and velocity. High-risk transactions are
  held or rejected before escrow.
- **Verification steps.** If the template requires SMS or 2FA verification,
  the transaction pauses here until the code is confirmed.

A transaction that fails Verify moves to `FAILED` with a reason. Nothing
was funded, so there is nothing to unwind.

## Phase 2: Fund

**States: `ESCROWED` (and `PENDING_USER_ACTION` while waiting on an external wallet)**

Funds lock into the escrow contract defined by your template. A webhook
fires when escrow confirms on-chain.

What runs here:

- **Escrow funding.** For `coinbax` orchestration, funds lock in the smart
  contract. For `raw`, the direct transfer executes. Either way, the
  on-chain transaction hash is recorded before the state advances.
- **External wallet flows.** When the sender signs from their own wallet,
  the transaction waits in `PENDING_USER_ACTION` until the funding
  transaction lands on-chain.
- **POST_ESCROW controls.** Time delays set the release timestamp; ongoing
  transaction monitoring registers the payment for the escrow period.

The `transaction.escrowed` webhook carries the escrow address and hash, so
your system can reconcile against the chain directly.

## Phase 3: Confirm

**States: `IN_REVIEW`, `DISPUTED`**

Review windows, approvals, and rollback triggers execute. Your integration
can hold, approve, or recall here.

What runs here:

- **Review windows.** RAW transactions hold in `IN_REVIEW` (72 hours by
  default) before completing. Approvals can close the window early.
- **Time delays.** COINBAX transactions wait out the configured delay
  before auto-release. The delay is set by the template's TimeDelay
  control, from one minute up to 30 days.
- **PRE_RELEASE controls.** Final compliance and risk checks run
  immediately before release. A control that fails here blocks the release.
- **Disputes and refunds.** Either party can dispute; the platform can
  refund. Both interrupt the path to settlement while funds are still
  recoverable.

Confirm is the phase that makes stablecoin payments operationally
reversible: funds are committed on-chain but not yet released, so approvals
and recalls still have teeth.

## Phase 4: Settle

**States: `COMPLETED`, `REFUNDED` (plus `RESCINDED` and `FAILED` as the other terminal states)**

The contract releases funds and records the result. Terminal states arrive
by webhook with the full audit trail.

What runs here:

- **Release.** The escrow contract releases funds to the receiver
  (`COMPLETED`) or returns them to the sender (`REFUNDED`).
- **Audit trail.** Every control execution, state transition, and on-chain
  reference is frozen on the transaction record. Terminal states cannot
  transition again.
- **Notifications.** The final webhook (`transaction.completed`,
  `transaction.refunded`, or `transaction.rescinded`) closes the loop for
  your integration.

## State-to-phase map

| Phase | States | Webhook events |
|---|---|---|
| Verify | `PENDING`, `RISK_REVIEW` | `transaction.created`, `transaction.failed` |
| Fund | `PENDING_USER_ACTION`, `ESCROWED` | `transaction.escrowed` |
| Confirm | `IN_REVIEW`, `DISPUTED` | dispute events |
| Settle | `COMPLETED`, `REFUNDED`, `RESCINDED`, `FAILED` | `transaction.completed`, `transaction.refunded`, `transaction.rescinded` |

## Why a framework

The framework is the contract between you and Coinbax. Controls always
execute at a defined phase (PRE_ESCROW controls in Verify, POST_ESCROW in
Fund, PRE_RELEASE in Confirm), states always advance in order, and terminal
states are final. That predictability is what lets you attach approvals,
limits, and recourse to money that otherwise settles instantly.

## Next steps

- [Payment controls](/docs/concepts/controls): the rules that execute in each phase
- [Your first transaction](/docs/getting-started/first-transaction): watch one payment cross all four phases
- [Webhooks](/docs/api/webhooks): receive every phase transition as an event

---

# Payment Controls

> Composable rules attached to templates that execute at fixed points in the transaction lifecycle: time delays, verification, screening, and limits.
> Source: https://developers.coinbax.com/docs/concepts/controls

Controls are the core primitive of the Coinbax platform: composable rules
that attach to a template and execute automatically at fixed points in the
transaction lifecycle. A time delay before release, an SMS verification
before escrow, a sanctions screen on both parties, an amount limit per
transaction: each is a control, and a template composes them into a payment
policy that every transaction inherits.

## How controls execute

Every control declares an **execution phase**, which pins it to a point in
the [Coinbax Execution Framework](/docs/concepts/execution-framework):

| Phase | When it runs | Typical controls |
|---|---|---|
| `PRE_ESCROW` | Before any funds move (Verify) | Compliance screening, sanctions checks, 2FA and SMS verification, amount limits |
| `POST_ESCROW` | After funds lock in escrow (Fund) | Time delays, ongoing transaction monitoring |
| `PRE_RELEASE` | Immediately before funds release (Confirm) | Final risk validation before settlement |

Within a phase, controls run in their declared `executionOrder`. A required
control that fails stops the transaction: a PRE_ESCROW failure means no
funds ever move, and a PRE_RELEASE failure blocks the release while funds
are still recoverable in escrow.

Every execution is recorded on the transaction. Each result captures the
control type, phase, outcome, duration, and any data it produced (a
computed release timestamp, a risk score), giving you a complete audit
trail per payment.

## Control types

### Time delays

Holds escrowed funds for a configured period before auto-release, from one
minute up to 30 days. The control computes a release timestamp at
POST_ESCROW; a background job releases the escrow once the timestamp
passes and all PRE_RELEASE controls succeed.

```json
{
  "type": "TimeDelay",
  "executionPhase": "POST_ESCROW",
  "config": { "delayMinutes": 5, "autoRelease": true }
}
```

The delay is the recall window: refunds, rescinds, and disputes all operate
against funds that are committed but not yet released.

### Verification (2FA and SMS)

Requires a party to confirm the payment with a one-time code before escrow.
The transaction pauses in an awaiting-verification state until the code is
submitted; codes expire and can be resent. Verification happens either
through your own UI (`POST /controls/verify-2fa` or
`POST /controls/verify-twilio-sms` with the transaction ID and code) or
through the hosted verification link Coinbax sends by SMS.

```json
{
  "type": "TwilioSMS",
  "executionPhase": "PRE_ESCROW",
  "config": { "requiredFor": ["sender"], "codeExpiration": 5 }
}
```

### Compliance screening

Screens wallet addresses, customers, and transactions against risk and
sanctions data before funds move. Screening controls take a risk threshold
(0 to 100) and can be configured to fail the transaction outright when the
threshold is exceeded, or to flag it for review.

```json
{
  "type": "ComplianceCheck",
  "executionPhase": "PRE_ESCROW",
  "config": { "riskThreshold": 70, "checkBothParties": true, "failOnHighRisk": true }
}
```

Transaction monitoring variants register the payment at POST_ESCROW and
re-validate at PRE_RELEASE, so a risk signal that emerges during the escrow
window still blocks settlement.

### Amount limits

Caps the value of a single transaction under the template. Runs at
PRE_ESCROW, so an over-limit payment is rejected before any funds move.

## Templates carry controls

You do not attach controls to individual transactions. Controls live on
**templates**: versioned, reusable payment policies managed in your
workspace. A template declares its controls, their configuration, their
phases, and their order.

When you create a transaction with a `templateId`, the transaction inherits
the template's controls exactly as published:

```bash
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": "0x...",
    "toAddress": "0x...",
    "amount": 250,
    "orchestrationType": "coinbax",
    "templateId": "<template-id>"
  }'
```

Templates are semantically versioned, and every version change is tracked.
Because the transaction records which template and version it ran under,
plus the result of every control execution, you can answer "what policy
governed this payment" for any transaction, ever.

## Design principles

- **Composable.** Each control is independent. A template stacks as many as
  the payment policy needs.
- **Deterministic.** Controls run at declared phases in declared order.
  There are no side channels around them.
- **Fail-safe.** Required controls block the transaction when they fail or
  when their upstream data source is unreachable. Uncertainty resolves
  toward not moving money.
- **Auditable.** Every execution is logged with its outcome and timing on
  the transaction record.

## Next steps

- [The Coinbax Execution Framework](/docs/concepts/execution-framework): the phases controls execute in
- [Your first transaction](/docs/getting-started/first-transaction): controls running on a live staging payment
- [Payments API reference](/reference/coinbax-api/): the verification endpoints and template fields

---

# Authentication

> API key, OAuth 2.0 client credentials, and JWT authentication for the Coinbax Payments and Workspace APIs.
> Source: https://developers.coinbax.com/docs/api/authentication

Coinbax has two API surfaces with different authentication:

| API | Base URL (staging) | Auth |
|---|---|---|
| Payments API | `https://api-staging.coinbax.com/api/v1` | `X-API-Key` header, or OAuth 2.0 Bearer token |
| Workspace API | `https://core-staging.coinbax.com/api/v1` | `Authorization: Bearer <JWT>` |

Production bases are `https://api.coinbax.com/api/v1` and
`https://core.coinbax.com/api/v1`. Staging credentials only work against
staging; the environments share nothing.

## API keys (Payments API)

The simplest way to call the Payments API from a backend:

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

Key facts:

- **Shown once.** The key is returned a single time at creation and cannot
  be retrieved later. Store it in a secret manager immediately.
- **Scoped.** Every key carries a set of [scopes](/docs/api/scopes) that
  bound what it can do. New keys default to read-only scopes; grant write
  scopes deliberately.
- **Server-side only.** Never ship an API key in a browser, mobile app, or
  public repository. If a key leaks, regenerate it via
  `POST /auth/api-key/regenerate`.

## OAuth 2.0 client credentials (service-to-service)

For service-to-service integrations, and for any client where you want
short-lived credentials instead of a long-lived key, use the OAuth 2.0
`client_credentials` grant. You exchange a client ID and secret for a
Bearer token, then send that token on Payments API requests.

### Create an OAuth client

OAuth clients are created with an admin-scoped API key:

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/oauth/clients \
  -H "X-API-Key: $COINBAX_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Backend Service",
    "scopes": ["read:transactions", "write:transactions"],
    "grantTypes": ["client_credentials"]
  }'
```

The response includes `clientId` and `clientSecret`. Like API keys, the
secret is shown once.

### Exchange credentials for a token

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "coinbax_client_...",
    "client_secret": "coinbax_secret_...",
    "scope": "read:transactions write:transactions"
  }'
```

`scope` is optional and space-separated; omit it to receive all scopes
granted to the client. The token arrives in the standard response envelope:

```json
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOi...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "read:transactions write:transactions"
  },
  "meta": { "timestamp": "...", "requestId": "..." },
  "error": null
}
```

Then call the API with the token:

```bash
curl https://api-staging.coinbax.com/api/v1/transactions \
  -H "Authorization: Bearer eyJhbGciOi..."
```

### Token lifecycle: cache, refresh, retry

Do not request a new token per API call. The correct pattern:

1. **Cache** the `access_token` with its computed expiry
   (`now + expires_in` seconds).
2. **Refresh early.** Treat the token as expired about 60 seconds before
   its actual expiry so in-flight requests never race the deadline.
3. **Share in-flight refreshes.** If multiple concurrent requests find the
   cache empty, they should await one token request, not fan out N of them.
4. **Retry on 401.** If a request returns 401 with a token you believed
   valid (revocation, clock skew), discard the cached token, fetch a fresh
   one, and retry the request once.

```javascript
let cached = null; // { token, expiresAt }
let inflight = null;

async function getAccessToken() {
  if (cached && Date.now() < cached.expiresAt - 60_000) return cached.token;
  inflight ??= fetchToken().finally(() => { inflight = null; });
  cached = await inflight;
  return cached.token;
}

async function fetchToken() {
  const res = await fetch(`${BASE}/oauth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.COINBAX_CLIENT_ID,
      client_secret: process.env.COINBAX_CLIENT_SECRET,
    }),
  });
  const { data } = await res.json();
  return { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
}
```

Tokens can be revoked with `POST /oauth/revoke`, and all tokens for a
client with `POST /oauth/clients/{clientId}/revoke-all-tokens`.

## JWT (Workspace API)

The Workspace API authenticates humans and dashboard-style integrations
with JWTs:

```bash
# Log in to obtain tokens
curl -X POST https://core-staging.coinbax.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "..." }'

# Use the access token
curl https://core-staging.coinbax.com/api/v1/workspaces/me \
  -H "Authorization: Bearer <access-token>"
```

Access tokens expire after one hour. Use `POST /auth/refresh` to obtain a
new access token without re-authenticating, and `POST /auth/logout` to
invalidate the session.

## Choosing a method

| You are building | Use |
|---|---|
| A backend that creates payments | API key, or OAuth for short-lived credentials |
| A service-to-service integration | OAuth 2.0 client credentials |
| A tool against workspace data (customers, settings, webhooks) | Workspace API with JWT |
| Anything in a browser or mobile app | OAuth via your own backend proxy; never embed keys or secrets client-side |

## Next steps

- [API scopes](/docs/api/scopes): what each scope grants and how the hierarchy works
- [Errors and the response envelope](/docs/api/errors): what 401 and 403 responses look like
- [Payments API reference](/reference/coinbax-api/): the auth and OAuth endpoints in full

---

# API Scopes

> Every Payments API scope, what it grants, and the hierarchy rules that expand write scopes to include reads.
> Source: https://developers.coinbax.com/docs/api/scopes

Every Payments API credential (API key or OAuth client) carries a set of
scopes that bound what it can do. Endpoints declare required scopes; a
request whose credential lacks them is rejected with 403 before any
business logic runs.

Scopes follow the format `<action>:<resource>`, for example
`write:transactions`.

## All scopes

### Transactions

| Scope | Grants |
|---|---|
| `read:transactions` | View transactions and their status |
| `write:transactions` | Create and update transactions |
| `cancel:transactions` | Refund transactions |
| `rescind:transactions` | Rescind transactions during hold period |

### Customers

| Scope | Grants |
|---|---|
| `read:customers` | View customer information |
| `write:customers` | Create and update customers |

### Templates

| Scope | Grants |
|---|---|
| `read:templates` | View payment templates |
| `write:templates` | Create and update templates |

### Disputes

| Scope | Grants |
|---|---|
| `read:disputes` | View disputes |
| `write:disputes` | Create and respond to disputes |
| `submit:evidence` | Submit evidence for disputes |

### Webhooks

| Scope | Grants |
|---|---|
| `read:webhooks` | View webhook configurations |
| `write:webhooks` | Create and update webhooks |

### Compliance

| Scope | Grants |
|---|---|
| `read:compliance` | View compliance verifications |
| `write:compliance` | Create compliance verification requests |

### Platform

| Scope | Grants |
|---|---|
| `read:platform` | View own platform information |
| `write:platform` | Update own platform settings |
| `manage:api-keys` | Create and revoke API keys |

### Admin

| Scope | Grants |
|---|---|
| `admin:platform` | Full platform access (all scopes) |

## Hierarchy rules

You never need to list a read scope alongside its write scope. Write-class
scopes automatically include the corresponding read scope:

| This scope | Also grants |
|---|---|
| `write:transactions` | `read:transactions` |
| `cancel:transactions` | `read:transactions` |
| `rescind:transactions` | `read:transactions` |
| `write:customers` | `read:customers` |
| `write:templates` | `read:templates` |
| `write:disputes` | `read:disputes` |
| `submit:evidence` | `read:disputes` |
| `write:webhooks` | `read:webhooks` |
| `write:compliance` | `read:compliance` |
| `write:platform` | `read:platform` |
| `manage:api-keys` | `read:platform` |

`admin:platform` grants every scope. It exists for administrative tooling;
do not use it for day-to-day integrations.

## Defaults

New API keys are created with read-only scopes unless you specify
otherwise:

- `read:transactions`
- `read:customers`
- `read:platform`

Request write scopes explicitly at key creation:

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/auth/api-key \
  -H "X-API-Key: $COINBAX_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payments Integration",
    "scopes": ["read:transactions", "write:transactions", "read:customers"]
  }'
```

OAuth clients declare their scopes at creation the same way, and a token
request can narrow them further with the optional `scope` parameter. See
[authentication](/docs/api/authentication).

## When a scope is missing

A request without the required scope returns 403 with the code
`INSUFFICIENT_SCOPES`. The error message names the scopes the endpoint
requires and the scopes your credential actually has, so the fix is always
explicit:

```
Insufficient permissions. Required scopes: [write:transactions].
Your key has: [read:transactions, read:customers]
```

Handle 403 distinctly from 401: a 401 means the credential itself is
invalid, a 403 means the credential is valid but under-scoped. See
[errors and the response envelope](/docs/api/errors).

## Practices that hold up

1. **Least privilege.** Grant only the scopes the integration uses.
2. **One key per integration.** Separate keys mean a leak or a revocation
   affects one system, and audit logs attribute activity cleanly.
3. **Start read-only.** Ship against the default read scopes, then add
   write scopes as flows come online.
4. **Reserve `admin:platform`.** Administrative tools only.

---

# Errors and the Response Envelope

> The unified success/data/meta/error envelope, error codes by HTTP status, and how to build one parser for every API outcome.
> Source: https://developers.coinbax.com/docs/api/errors

Every Coinbax API response, success or failure, arrives in the same
envelope. Write one parser and it handles every endpoint and every outcome.

## The envelope

```json
{
  "success": true,
  "data": { "id": "9f8b3c2a-...", "status": "escrowed" },
  "meta": {
    "timestamp": "2026-07-16T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "error": null
}
```

| Field | Type | Meaning |
|---|---|---|
| `success` | boolean | `true` on success, `false` on error |
| `data` | object or null | The payload; `null` on error |
| `meta` | object | Timestamp, request ID, pagination, and (on errors) path and method |
| `error` | object or null | Error details; `null` on success |

List endpoints add pagination to `meta`:

```json
{
  "meta": {
    "timestamp": "...",
    "requestId": "...",
    "pagination": {
      "page": 2,
      "limit": 20,
      "total": 150,
      "totalPages": 8,
      "hasNextPage": true,
      "hasPreviousPage": true
    }
  }
}
```

## Error responses

On failure, `success` is `false`, `data` is `null`, and `error` carries the
detail:

```json
{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-07-16T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": { "errors": ["amount: must be a positive number"] }
  }
}
```

The `error` object:

| Field | Type | Meaning |
|---|---|---|
| `code` | string | Stable machine-readable code; branch on this, not on `message` |
| `message` | string | Human-readable summary |
| `statusCode` | number | The HTTP status, mirrored into the body |
| `details` | object, optional | Field-level validation errors or additional context |

## Error codes by status

| HTTP status | Code | When you see it |
|---|---|---|
| 400 | `VALIDATION_ERROR` | A request field failed validation; `details` names the field |
| 400 | `INVALID_REQUEST` | Malformed request body or parameters |
| 401 | `UNAUTHORIZED` | Missing, invalid, or expired credential |
| 403 | `FORBIDDEN` / `INSUFFICIENT_SCOPES` | Valid credential, but it lacks a required [scope](/docs/api/scopes) |
| 404 | `NOT_FOUND` | The resource does not exist or belongs to another workspace |
| 409 | `CONFLICT` | Duplicate resource or an invalid state transition (for example refunding a completed transaction) |
| 422 | `UNPROCESSABLE_ENTITY` | The request is well-formed but fails a business rule |
| 429 | `RATE_LIMIT_EXCEEDED` | Too many requests; honor `Retry-After` (see [rate limits](/docs/api/rate-limits)) |
| 500 | `INTERNAL_SERVER_ERROR` | Unexpected server error |
| 503 | `SERVICE_UNAVAILABLE` | Temporary outage; retry with backoff |

500-level responses are sanitized: they never leak stack traces or internal
detail in production. Everything you need for support is in
`meta.requestId`.

## One parser for every outcome

Because the shape never varies, error handling collapses to a single
function:

```javascript
async function coinbax(path, init) {
  const res = await fetch(`${BASE}${path}`, init);
  const body = await res.json();
  if (!body.success) {
    const err = new Error(body.error.message);
    err.code = body.error.code;
    err.status = body.error.statusCode;
    err.requestId = body.meta.requestId;
    throw err;
  }
  return body.data;
}
```

Branch on `error.code`, never on message text. Messages are for humans and
may change; codes are stable.

## Request IDs and support

Every response carries a `meta.requestId` (also returned in the
`X-Request-ID` response header). It traces the request through the whole
platform.

- **Log it** alongside your own request logs on every error.
- **Send it** when opening an integration to make your requests traceable
  end to end: pass your own ID in the `X-Request-ID` request header and the
  API will echo it back instead of generating one.
- **Quote it** when contacting support. A request ID plus a timestamp lets
  us find the exact request, its control executions, and its outcome.

## Next steps

- [Rate limits](/docs/api/rate-limits): handling 429 with backoff
- [API scopes](/docs/api/scopes): resolving 403 responses
- [Payments API reference](/reference/coinbax-api/): per-endpoint error documentation

---

# Rate Limits

> Per-tier request limits, the rate limit response headers, and how to handle 429 responses with exponential backoff.
> Source: https://developers.coinbax.com/docs/api/rate-limits

Coinbax APIs enforce tier-based rate limits per credential. Limits exist to
keep the platform predictable for every integration; well-behaved clients
that respect the response headers never hit them.

## Tiers

| Tier | Limit | Applies to |
|---|---|---|
| Public | 20 req/min | Unauthenticated endpoints |
| Standard | 100 req/min | Regular authenticated API calls |
| High-frequency | 1000 req/min | Session polling and other frequent-access endpoints |
| Admin | 50 req/min | Administrative operations (deliberately strict) |

Endpoints are assigned to tiers server-side; you do not select a tier. Most
of your traffic falls under Standard.

## Response headers

Every response tells you where you stand:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1735073400
```

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Requests allowed in the current window |
| `X-RateLimit-Remaining` | Requests left in the window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |
| `Retry-After` | Seconds to wait; sent on 429 responses only |

## When you exceed a limit

The API returns 429 with the standard envelope
(`error.code: "RATE_LIMIT_EXCEEDED"`) and a `Retry-After` header:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 42
```

Two rules:

1. **Honor `Retry-After` when present.** It is the authoritative wait time.
2. **Fall back to exponential backoff with jitter** when it is absent or
   when retrying network-level failures.

## Backoff implementation

```javascript
async function coinbaxWithRetry(path, init, maxRetries = 5) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(`${BASE}${path}`, init);

    if (res.status !== 429) return res;
    if (attempt >= maxRetries) {
      throw new Error(`Rate limited after ${maxRetries} retries`);
    }

    const retryAfter = res.headers.get("Retry-After");
    const waitMs = retryAfter
      ? Number(retryAfter) * 1000
      // Exponential backoff with full jitter: 1s, 2s, 4s, 8s, 16s (capped)
      : Math.random() * Math.min(1000 * 2 ** attempt, 30_000);

    await new Promise((r) => setTimeout(r, waitMs));
  }
}
```

The jitter matters: if a burst of workers all hit the limit together, fixed
backoff makes them retry together and hit it again. Randomized waits spread
the retries out.

## Staying under the limits

- **Prefer webhooks to polling.** One [webhook subscription](/docs/api/webhooks)
  replaces a polling loop entirely; you receive every state transition as
  it happens instead of spending your budget asking.
- **Watch `X-RateLimit-Remaining`.** Treat a low value as a signal to slow
  down before you hit 429, not after.
- **Batch where the API supports it.** `POST /transactions/batch` creates
  multi-recipient payments in one request.
- **Cache stable reads.** Template configuration and platform settings
  change rarely; do not re-fetch them per transaction.
- **Use one credential per integration.** Limits apply per credential, so
  separate integrations do not consume each other's budget, and a noisy
  deploy cannot starve an unrelated system.

## Next steps

- [Errors and the response envelope](/docs/api/errors): the 429 response body in context
- [Webhooks](/docs/api/webhooks): event delivery instead of polling

---

# Webhooks

> Subscribe to transaction lifecycle events, verify HMAC signatures, and rely on retries with circuit breaker protection.
> Source: https://developers.coinbax.com/docs/api/webhooks

Webhooks push every transaction state transition to your endpoint as it
happens. They are the recommended integration pattern: one subscription
replaces a polling loop, and delivery comes with signatures, retries, and a
30-day delivery log.

## Register a subscription

```bash
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", "transaction.refunded", "transaction.failed"]
  }'
```

The response includes the subscription's signing secret. Like API keys, it
is shown once; store it securely. Requires the `write:webhooks`
[scope](/docs/api/scopes).

You can register multiple subscriptions, each with its own URL, event
selection, and secret. An optional `ipWhitelist` restricts which addresses
may receive deliveries for the subscription. Manage subscriptions with
`GET/PATCH/DELETE /webhooks/{id}`, and send a test delivery with
`POST /webhooks/{id}/test`.

## Event types

| Event | Fires when |
|---|---|
| `transaction.created` | A transaction is created; always the first event in a lifecycle |
| `transaction.escrowed` | Funds lock on-chain in the escrow contract |
| `transaction.completed` | Funds released to the receiver (terminal) |
| `transaction.failed` | A pre-escrow control failed or risk rejected the transaction (terminal) |
| `transaction.refunded` | Funds returned to the sender (terminal) |
| `transaction.rescinded` | The sender cancelled during the hold period (terminal) |
| `dispute.created` | A dispute is opened |
| `dispute.resolved` | A dispute is resolved |
| `dispute.escalated` | A dispute escalates to the next resolution tier |
| `evidence.submitted` | Evidence is submitted on a dispute |

The canonical, always-current list is available at
`GET /webhooks/events/types`.

## Payload shape

Deliveries are HTTPS POSTs with a JSON body. Transaction events carry the
transaction plus event-specific fields:

```json
// transaction.escrowed
{
  "transaction": { "id": "9f8b3c2a-...", "status": "escrowed" },
  "escrowAddress": "0x...",
  "txHash": "0x..."
}
```

```json
// transaction.refunded
{
  "transaction": { "id": "9f8b3c2a-...", "status": "refunded" },
  "reason": "Customer request"
}
```

Each delivery includes these headers:

| Header | Contents |
|---|---|
| `X-Webhook-Event` | The event type, for example `transaction.completed` |
| `X-Webhook-Signature` | HMAC-SHA256 hex digest of the request body, keyed by your secret |
| `X-Webhook-Delivery` | Unique delivery ID, for idempotency |

## Verify the signature

Every delivery is signed. Verify before trusting anything in the payload:

```javascript
import crypto from "node:crypto";

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected),
  );
}
```

Two details that bite people:

- **Verify against the raw request body**, not re-serialized parsed JSON.
  Re-serialization can reorder keys and change bytes, which breaks the HMAC.
- **Use a timing-safe comparison** (`crypto.timingSafeEqual` or your
  language's equivalent), never `===` on the hex strings.

Reject any request whose signature does not match.

## Delivery, retries, and the circuit breaker

- **At-least-once.** Deliveries can repeat. Dedupe on `X-Webhook-Delivery`
  within a reasonable window (24 hours is a good default).
- **Respond fast.** Coinbax waits up to 30 seconds for a 2xx response.
  Acknowledge immediately and process asynchronously; a slow handler is
  indistinguishable from a failing one.
- **Retries.** Non-2xx responses, timeouts, and network errors are retried
  with exponential backoff.
- **Circuit breaker.** Each subscription has a circuit breaker. Repeated
  failures trip it OPEN, pausing deliveries so a broken endpoint does not
  accumulate an unbounded retry queue. It transitions to HALF_OPEN to test
  recovery and closes again once deliveries succeed. You can force a reset
  with `POST /webhooks/{id}/reset-circuit-breaker`.
- **Delivery logs.** `GET /webhooks/{id}/delivery-logs` returns a 30-day
  audit trail with request and response details per delivery, which is the
  fastest way to debug a misbehaving endpoint.

## Rotate the secret

Secrets rotate with zero downtime using dual signing:

1. `POST /webhooks/{id}/rotate-secret` returns a new secret. During the
   grace period Coinbax signs deliveries with both the old and the new
   secret, so your endpoint can verify with either.
2. Deploy the new secret to your handler.
3. `POST /webhooks/{id}/complete-rotation` retires the old secret.

Rotate immediately if a secret may have been exposed, and on your normal
credential rotation schedule otherwise.

## Handler checklist

- [ ] Verify the HMAC signature against the raw body, timing-safe
- [ ] Dedupe on `X-Webhook-Delivery`
- [ ] Return 2xx quickly; process async
- [ ] Treat event ordering as advisory; fetch the transaction with
      `GET /transactions/{id}` when you need authoritative current state
- [ ] Serve HTTPS with a valid certificate

## Next steps

- [Your first transaction](/docs/getting-started/first-transaction): the events in lifecycle order
- [Errors and the response envelope](/docs/api/errors): the envelope your GET calls return
- [Payments API reference](/reference/coinbax-api/): every webhook endpoint

---

# Staging and Testnets

> Staging is testnet-only and enforced at startup; the supported test networks, faucets, and the mainnet-only production rule.
> Source: https://developers.coinbax.com/docs/resources/staging-and-testnets

Coinbax runs two fully separated environments. Staging only ever touches
test networks; production only ever touches mainnets. The separation is not
a convention: it is enforced in infrastructure. A staging deployment
configured with a mainnet network refuses to start, and the same guard
works in reverse for production. There is no configuration mistake that
sends staging traffic to real funds.

| Environment | Networks | Payments API base |
|---|---|---|
| Staging | Testnet only | `https://api-staging.coinbax.com/api/v1` |
| Production | Mainnet only | `https://api.coinbax.com/api/v1` |

Credentials are environment-specific: a staging API key is meaningless
against production and vice versa.

## Supported testnets (staging)

Base Sepolia is the primary staging network and the one used throughout
these guides.

| Network | `blockchainNetwork` value | Chain ID |
|---|---|---|
| Base Sepolia (primary) | `base-sepolia` | `84532` |
| Ethereum Sepolia | `ethereum-sepolia` | `11155111` |
| Optimism Sepolia | `optimism-sepolia` | `11155420` |
| Arbitrum Sepolia | `arbitrum-sepolia` | `421614` |
| Solana Devnet | `solana-devnet` | devnet |

### Network coercion on staging

Staging is forgiving about network names: if you send a mainnet name (for
example `base`) to staging, it is coerced to the testnet counterpart
(`base-sepolia`). This lets the same integration code run against both
environments with only the base URL and credentials changing. Production is
not forgiving in the other direction: a testnet network name sent to
production is rejected with `TESTNET_NOT_ALLOWED_IN_PRODUCTION`.

If you omit `blockchainNetwork`, transactions default to the environment's
Base network: `base-sepolia` on staging, `base` on production.

## Test funds

**Test USDC on Base Sepolia:**

```
0x036CbD53842c5426634e7929541eC2318f3dCF7e
```

Get testnet USDC from the [Circle faucet](https://faucet.circle.com); select
Base Sepolia as the network. Circle's faucet also covers the other
supported testnets.

You will also need a small amount of testnet ETH (or the network's native
token) for gas when funding escrows from an external wallet. Any public
Base Sepolia faucet works.

Testnet tokens have no value. Treat staging balances as disposable.

## Production networks (mainnet only)

| Network | `blockchainNetwork` value | Chain ID |
|---|---|---|
| Base | `base` | `8453` |
| Ethereum | `ethereum` | `1` |
| Optimism | `optimism` | `10` |
| Arbitrum | `arbitrum` | `42161` |
| Solana | `solana` | mainnet-beta |

Production access is provisioned separately from staging; talk to the
Coinbax team when you are ready to go live.

## Recommended workflow

1. **Build on staging against Base Sepolia.** It is the primary network,
   has the deepest tooling support, and the faucets are reliable.
2. **Exercise the whole lifecycle**, including the endings you hope never
   to use: refunds, rescinds, failed compliance checks, disputes. Staging
   escrows are free to abandon.
3. **Point your webhook endpoint at a staging URL** and verify signature
   handling and dedupe before production traffic depends on it.
4. **Promote by changing base URL and credentials only.** If your staging
   integration needed any other change to work in production, that is a
   finding worth investigating before launch.

## Next steps

- [Getting started](/docs/getting-started/): staging credentials and constants
- [Your first transaction](/docs/getting-started/first-transaction): a full lifecycle on Base Sepolia
- [API versioning](/docs/resources/versioning): how the API surface evolves under you

---

# API Versioning

> URL-based versioning with /api/v1 current, the deprecation policy for unversioned routes, and how breaking versus additive changes are handled.
> Source: https://developers.coinbax.com/docs/resources/versioning

Coinbax APIs are versioned in the URL path. `v1` is the current version
across both API surfaces:

```
https://api.coinbax.com/api/v1/transactions
https://core.coinbax.com/api/v1/workspaces
```

Every response includes the version header:

```
X-API-Version: v1
```

Always build against versioned paths. The version in the URL is the
contract: within a version, we do not break you.

## Deprecation: unversioned Workspace API routes

Unversioned `/api/*` routes on the Workspace API predate the versioning
scheme. They are **deprecated with a sunset of June 2026**. They continue
to work until then, and every response on a deprecated route carries
standard deprecation headers (RFC 8594):

```
Deprecation: true
Sunset: 2026-06-01
Link: </api/v1>; rel="successor-version"
```

Migration is mechanical: insert `/v1` after `/api` in your base URL. The
handlers are the same; only the path changes.

```bash
# Deprecated
https://core.coinbax.com/api/workspaces/me

# Current
https://core.coinbax.com/api/v1/workspaces/me
```

If your HTTP client can log response headers, alert on `Deprecation: true`
so a deprecated call path cannot hide in your codebase until the sunset
date.

## How changes are handled

### Additive changes (no new version)

Within `v1`, changes are backward compatible only:

- New endpoints
- New optional request fields
- New response fields
- New enum values where the field is documented as extensible
- New webhook event types

Two consequences for your integration:

1. **Ignore unknown response fields.** Deserialize leniently; a new field
   appearing in `data` is normal and expected.
2. **Subscribe to webhook events by name.** New event types will not be
   delivered to you unless you subscribe to them.

### Breaking changes (new version)

Changes that would break a correct client get a new version:

- Removing or renaming fields or endpoints
- Changing a field's type or semantics
- Restructuring request or response formats

A new version means the old one enters a deprecation window, not an
immediate cutoff. The standard timeline:

1. **Day 0.** The new version ships; the old version is marked deprecated
   and starts returning `Deprecation` and `Sunset` headers.
2. **Transition window (90 days minimum).** Both versions work side by
   side. Migrate at your pace within the window.
3. **Sunset.** The old version is removed on the date in the `Sunset`
   header.

Usage of deprecated endpoints is monitored, and integrations still on a
deprecated surface near its sunset are contacted before removal.

## Practical guidance

- **Pin the versioned base URL in configuration**, not in call sites:

  ```bash
  export COINBAX_API_URL=https://api.coinbax.com/api/v1
  export COINBAX_CORE_URL=https://core.coinbax.com/api/v1
  ```

- **Check for deprecation headers** in responses as part of routine
  monitoring.
- **Test against staging first.** Staging receives changes before
  production, so exercising your integration at
  `https://api-staging.coinbax.com/api/v1` catches surprises early. See
  [staging and testnets](/docs/resources/staging-and-testnets).

## Next steps

- [Errors and the response envelope](/docs/api/errors): the stable response contract within a version
- [Payments API reference](/reference/coinbax-api/): the current v1 surface

---

# MCP Server

> Connect AI agents to the Coinbax docs over the Model Context Protocol to search guides, list endpoints, and fetch schemas.
> Source: https://developers.coinbax.com/docs/resources/mcp

This site runs a public, read-only [Model Context Protocol](https://modelcontextprotocol.io)
server at `https://developers.coinbax.com/mcp`. Agents connected to it can
onboard to the Coinbax Platform, browse both API collections, and pull
endpoint schemas with runnable staging samples, all without scraping HTML.

## Connect

The server speaks stateless Streamable HTTP. No authentication is required.

**Claude Code**

```bash
claude mcp add --transport http coinbax-docs https://developers.coinbax.com/mcp
```

**Generic client configuration**

```json
{
  "mcpServers": {
    "coinbax-docs": {
      "url": "https://developers.coinbax.com/mcp"
    }
  }
}
```

## Tools

| Tool | Purpose |
|---|---|
| `getting_started` | Onboarding instructions: staging credentials, base URLs, testnet constants, first transaction. Call this first. |
| `list_collections` | The documented API collections with base URLs and OpenAPI download links. |
| `list_endpoints` | Endpoints of a collection (operationId, method, path, summary), optionally filtered by tag. |
| `get_endpoint` | Full markdown documentation for one endpoint: parameters, schemas, examples, curl against staging. |
| `get_guide` | Any guide on this site as raw markdown, by slug. |
| `search_docs` | Ranked full-text search across all guides and endpoints. |

## Other machine-readable surfaces

The MCP server is one of four equivalent surfaces. The same content is
available without MCP:

- [/llms.txt](/llms.txt): index of every page with markdown links
- [/llms-full.txt](/llms-full.txt): the entire corpus in one file
- Raw markdown variants: append `.md` to any page URL
- OpenAPI JSON: [/openapi/coinbax-api.json](/openapi/coinbax-api.json) and [/openapi/coinbax-core.json](/openapi/coinbax-core.json)

All four are generated from the same sources at build time, so they never
disagree with the HTML pages.

---

# Coinbax API

> Source: https://developers.coinbax.com/reference/coinbax-api/
> OpenAPI spec: https://developers.coinbax.com/openapi/coinbax-api.json

## Servers

- https://api.coinbax.com (Production)
- https://api-staging.coinbax.com (Staging)

## Endpoint groups

### Authentication (8 operations)

- `POST /api/v1/auth/api-key` Create new API key (https://developers.coinbax.com/reference/coinbax-api/authentication.md#authcontroller-createapikey)
- `POST /api/v1/auth/api-key/regenerate` Regenerate API key (https://developers.coinbax.com/reference/coinbax-api/authentication.md#authcontroller-regenerateapikey)
- `GET /api/v1/auth/platform/me` Get current platform (https://developers.coinbax.com/reference/coinbax-api/authentication.md#authcontroller-getcurrentplatform)
- `GET /api/v1/auth/platform/{id}` Get platform details (https://developers.coinbax.com/reference/coinbax-api/authentication.md#authcontroller-getplatform)
- `PUT /api/v1/auth/platform/{id}` Update platform (https://developers.coinbax.com/reference/coinbax-api/authentication.md#authcontroller-updateplatform)
- `DELETE /api/v1/auth/platform/{id}` Deactivate platform (https://developers.coinbax.com/reference/coinbax-api/authentication.md#authcontroller-deactivateplatform)
- `GET /api/v1/auth/platforms` List all platforms (https://developers.coinbax.com/reference/coinbax-api/authentication.md#authcontroller-listplatforms)
- `POST /api/v1/auth/verify` Verify API key (https://developers.coinbax.com/reference/coinbax-api/authentication.md#authcontroller-verifyapikey)

### Controls (2 operations)

- `POST /api/v1/controls/verify-2fa` Verify 2FA code (https://developers.coinbax.com/reference/coinbax-api/controls.md#controlscontroller-verify2fa)
- `POST /api/v1/controls/verify-twilio-sms` Verify Twilio SMS code (https://developers.coinbax.com/reference/coinbax-api/controls.md#controlscontroller-verifytwiliosms)

### Health (4 operations)

- `GET /api/v1/health` Complete health check (https://developers.coinbax.com/reference/coinbax-api/health.md#healthcontroller-check)
- `GET /api/v1/health/live` Liveness probe (https://developers.coinbax.com/reference/coinbax-api/health.md#healthcontroller-liveness)
- `GET /api/v1/health/ready` Readiness probe (https://developers.coinbax.com/reference/coinbax-api/health.md#healthcontroller-readiness)
- `GET /api/v1/sentry-test` Test Sentry integration (https://developers.coinbax.com/reference/coinbax-api/health.md#sentrytestcontroller-testsentry)

### JWKS (1 operations)

- `GET /.well-known/jwks.json` Get JSON Web Key Set (https://developers.coinbax.com/reference/coinbax-api/jwks.md#jwkscontroller-getjwks)

### OAuth 2.0 (10 operations)

- `GET /api/v1/oauth/clients` List OAuth clients (https://developers.coinbax.com/reference/coinbax-api/oauth-2-0.md#oauthcontroller-listclients)
- `POST /api/v1/oauth/clients` Create OAuth client (https://developers.coinbax.com/reference/coinbax-api/oauth-2-0.md#oauthcontroller-createclient)
- `GET /api/v1/oauth/clients/{clientId}` Get OAuth client details (https://developers.coinbax.com/reference/coinbax-api/oauth-2-0.md#oauthcontroller-getclient)
- `DELETE /api/v1/oauth/clients/{clientId}` Delete OAuth client (https://developers.coinbax.com/reference/coinbax-api/oauth-2-0.md#oauthcontroller-deleteclient)
- `PATCH /api/v1/oauth/clients/{clientId}` Update OAuth client (https://developers.coinbax.com/reference/coinbax-api/oauth-2-0.md#oauthcontroller-updateclient)
- `POST /api/v1/oauth/clients/{clientId}/revoke-all-tokens` Revoke all client tokens (https://developers.coinbax.com/reference/coinbax-api/oauth-2-0.md#oauthcontroller-revokeallclienttokens)
- `GET /api/v1/oauth/clients/{clientId}/stats` Get client token statistics (https://developers.coinbax.com/reference/coinbax-api/oauth-2-0.md#oauthcontroller-getclientstats)
- `POST /api/v1/oauth/revoke` Revoke access token (https://developers.coinbax.com/reference/coinbax-api/oauth-2-0.md#oauthcontroller-revoke)
- `GET /api/v1/oauth/scopes` List available OAuth scopes (https://developers.coinbax.com/reference/coinbax-api/oauth-2-0.md#oauthcontroller-listscopes)
- `POST /api/v1/oauth/token` OAuth 2.0 Token Endpoint (https://developers.coinbax.com/reference/coinbax-api/oauth-2-0.md#oauthcontroller-token)

### Platform (1 operations)

- `GET /api/v1/platform/config` Get platform configuration (https://developers.coinbax.com/reference/coinbax-api/platform.md#platformcontroller-getconfig)

### Transaction Stream (1 operations)

- `GET /api/v1/transactions/{id}/stream` Subscribe to real-time transaction updates (https://developers.coinbax.com/reference/coinbax-api/transaction-stream.md#transactionstreamcontroller-streamupdates)

### Transactions (25 operations)

- `GET /api/v1/transactions` List transactions with filters (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-findall)
- `POST /api/v1/transactions` Create a new transaction (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-create)
- `GET /api/v1/transactions/at-risk` Money-at-risk: count + age of funds stuck in non-terminal states (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-getatriskstatistics)
- `GET /api/v1/transactions/batch` List transaction batches with filters (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-findallbatches)
- `POST /api/v1/transactions/batch` Create a multi-recipient transaction batch (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-createbatch)
- `GET /api/v1/transactions/batch/{id}` Get a transaction batch by ID (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-findbatch)
- `POST /api/v1/transactions/batch/{id}/cancel` Manually cancel an unsubmitted batch (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-cancelbatch)
- `POST /api/v1/transactions/batch/{id}/submit-escrow-hash` Record the on-chain batchCreateEscrow transaction hash (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-submitbatchescrowhash)
- `POST /api/v1/transactions/batch/{id}/verify-2fa` Verify a 2FA code against a pending batch control (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-verifybatch2fa)
- `POST /api/v1/transactions/fee-preview` Preview platform fee for a transaction (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-previewfee)
- `POST /api/v1/transactions/quote` Create a fee quote for a pending transaction (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-createquote)
- `GET /api/v1/transactions/stats` Get transaction statistics (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-getstatistics)
- `GET /api/v1/transactions/template-config` Get sanitized template + controls config for a template ID (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-gettemplateconfig)
- `GET /api/v1/transactions/{id}` Get transaction by ID (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-findone)
- `POST /api/v1/transactions/{id}/authorize-release` Authorize release of an external-wallet escrow (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-authorizerelease)
- `GET /api/v1/transactions/{id}/bit-status` Get bit execution status for transaction (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-getbitstatus)
- `POST /api/v1/transactions/{id}/cancel` Cancel pre-escrow transaction the user never signed for (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-cancelpending)
- `POST /api/v1/transactions/{id}/complete` Complete transaction and release funds (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-complete)
- `POST /api/v1/transactions/{id}/refund` Refund transaction (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-refund)
- `POST /api/v1/transactions/{id}/rescind` Rescind transaction during hold period (sender only) (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-rescind)
- `POST /api/v1/transactions/{id}/resend-2fa` Resend 2FA verification code (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-resend2fa)
- `POST /api/v1/transactions/{id}/retry-bit/{bitId}` Retry a failed bit execution (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-retrybit)
- `POST /api/v1/transactions/{id}/submit-escrow-hash` Submit escrow transaction hash for external wallet (Transmitter) transactions (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-submitescrowhash)
- `POST /api/v1/transactions/{id}/submit-hash` Submit blockchain transaction hash for RAW transaction (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-submittransactionhash)
- `POST /api/v1/transactions/{id}/verify-2fa` Verify 2FA code for transaction (https://developers.coinbax.com/reference/coinbax-api/transactions.md#transactioncontroller-verify2fa)

### Verification (3 operations)

- `GET /api/v1/verify/{transactionId}` Get verification info for a transaction (public) (https://developers.coinbax.com/reference/coinbax-api/verification.md#verificationcontroller-getverificationinfo)
- `POST /api/v1/verify/{transactionId}/resend` Resend verification code (public) (https://developers.coinbax.com/reference/coinbax-api/verification.md#verificationcontroller-resendcode)
- `POST /api/v1/verify/{transactionId}/verify` Verify SMS code (public) (https://developers.coinbax.com/reference/coinbax-api/verification.md#verificationcontroller-verifycode)

### compliance (4 operations)

- `POST /api/v1/api/v1/compliance/verifications` Create a new verification request (https://developers.coinbax.com/reference/coinbax-api/compliance.md#compliancecontroller-createverification)
- `POST /api/v1/api/v1/compliance/verifications/check` Check verification status (https://developers.coinbax.com/reference/coinbax-api/compliance.md#compliancecontroller-checkverification)
- `GET /api/v1/api/v1/compliance/verifications/{id}` Get verification by ID (https://developers.coinbax.com/reference/coinbax-api/compliance.md#compliancecontroller-getverification)
- `POST /api/v1/api/v1/compliance/webhooks/persona` Webhook endpoint for Persona verification updates (https://developers.coinbax.com/reference/coinbax-api/compliance.md#compliancecontroller-handlepersonawebhook)

### disputes (6 operations)

- `GET /api/v1/disputes` Get all disputes for platform (https://developers.coinbax.com/reference/coinbax-api/disputes.md#disputecontroller-getdisputes)
- `POST /api/v1/disputes` Create a new dispute for a transaction (https://developers.coinbax.com/reference/coinbax-api/disputes.md#disputecontroller-createdispute)
- `GET /api/v1/disputes/{id}` Get dispute by ID (https://developers.coinbax.com/reference/coinbax-api/disputes.md#disputecontroller-getdispute)
- `POST /api/v1/disputes/{id}/escalate` Escalate dispute to next tier (https://developers.coinbax.com/reference/coinbax-api/disputes.md#disputecontroller-escalatedispute)
- `POST /api/v1/disputes/{id}/evidence` Submit evidence for a dispute (https://developers.coinbax.com/reference/coinbax-api/disputes.md#disputecontroller-submitevidence)
- `POST /api/v1/disputes/{id}/resolve` Resolve a dispute (https://developers.coinbax.com/reference/coinbax-api/disputes.md#disputecontroller-resolvedispute)

### webhooks (11 operations)

- `GET /api/v1/webhooks` List webhook subscriptions (https://developers.coinbax.com/reference/coinbax-api/webhooks.md#webhookcontroller-list)
- `POST /api/v1/webhooks` Create webhook subscription (https://developers.coinbax.com/reference/coinbax-api/webhooks.md#webhookcontroller-create)
- `GET /api/v1/webhooks/events/types` Get available webhook event types (https://developers.coinbax.com/reference/coinbax-api/webhooks.md#webhookcontroller-geteventtypes)
- `GET /api/v1/webhooks/{id}` Get webhook subscription (https://developers.coinbax.com/reference/coinbax-api/webhooks.md#webhookcontroller-get)
- `DELETE /api/v1/webhooks/{id}` Delete webhook subscription (https://developers.coinbax.com/reference/coinbax-api/webhooks.md#webhookcontroller-delete)
- `PATCH /api/v1/webhooks/{id}` Update webhook subscription (https://developers.coinbax.com/reference/coinbax-api/webhooks.md#webhookcontroller-update)
- `POST /api/v1/webhooks/{id}/complete-rotation` Complete secret rotation (https://developers.coinbax.com/reference/coinbax-api/webhooks.md#webhookcontroller-completerotation)
- `GET /api/v1/webhooks/{id}/delivery-logs` Get webhook delivery logs (https://developers.coinbax.com/reference/coinbax-api/webhooks.md#webhookcontroller-deliverylogs)
- `POST /api/v1/webhooks/{id}/reset-circuit-breaker` Reset circuit breaker (https://developers.coinbax.com/reference/coinbax-api/webhooks.md#webhookcontroller-resetcircuitbreaker)
- `POST /api/v1/webhooks/{id}/rotate-secret` Rotate webhook secret (https://developers.coinbax.com/reference/coinbax-api/webhooks.md#webhookcontroller-rotatesecret)
- `POST /api/v1/webhooks/{id}/test` Test webhook endpoint (https://developers.coinbax.com/reference/coinbax-api/webhooks.md#webhookcontroller-test)


---

# Authentication (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/authentication/
> Staging base URL: https://api-staging.coinbax.com

API key management and verification

## Create new API key

`POST /api/v1/auth/api-key`

- Auth: X-API-Key header
- Operation ID: `AuthController_createApiKey`

Generate a new API key for a platform. Requires an existing admin-scoped API key. The new API key is only shown once.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Platform name (3-100 characters) |
| `webhookUrl` | string | no | Webhook URL for receiving event notifications (must be HTTPS in production) |
| `settings` | object | no | Additional platform settings |
| `scopes` | array of enum ("read:transactions", "write:transactions", "cancel:transactions", "rescind:transactions", "read:customers", "write:customers", "read:templates", "write:templates", "read:disputes", "write:disputes", "submit:evidence", "read:webhooks", "write:webhooks", "read:compliance", "write:compliance", "read:platform", "write:platform", "manage:api-keys", "admin:platform") | no | API scopes to grant to this key. If not provided, defaults to read-only scopes. |

```json
{
  "name": "My Marketplace",
  "webhookUrl": "https://myapp.com/webhooks/coinbax",
  "settings": {
    "theme": "dark",
    "notifications": true
  },
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ]
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/auth/api-key \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My Marketplace",
  "webhookUrl": "https://myapp.com/webhooks/coinbax",
  "settings": {
    "theme": "dark",
    "notifications": true
  },
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ]
}'
```

### Responses

**201** API key created successfully

```json
{
  "apiKey": "cbx_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "platformId": "string",
  "platformName": "string",
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ],
  "createdAt": "2026-01-15T12:00:00.000Z",
  "warning": "Store this API key securely. It will not be shown again."
}
```

**400** Bad request

**401** Missing or invalid API key

**403** Caller lacks admin:platform scope

---

## Regenerate API key

`POST /api/v1/auth/api-key/regenerate`

- Auth: X-API-Key header
- Operation ID: `AuthController_regenerateApiKey`

Generate a new API key for an existing platform. The old key will be invalidated.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `platformId` | string | yes | Platform ID |

```json
{
  "platformId": "123e4567-e89b-12d3-a456-426614174000"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/auth/api-key/regenerate \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "platformId": "123e4567-e89b-12d3-a456-426614174000"
}'
```

### Responses

**200** API key regenerated successfully

```json
{
  "apiKey": "cbx_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "platformId": "string",
  "platformName": "string",
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ],
  "createdAt": "2026-01-15T12:00:00.000Z",
  "warning": "Store this API key securely. It will not be shown again."
}
```

**404** Platform not found

---

## Get current platform

`GET /api/v1/auth/platform/me`

- Auth: X-API-Key header
- Operation ID: `AuthController_getCurrentPlatform`

Get platform details for the authenticated API key

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-api-key` | header | string | yes |  |
| `X-API-Key` | header | string | yes | API key |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/auth/platform/me \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Current platform details

```json
{}
```

**401** Invalid or missing API key

---

## Get platform details

`GET /api/v1/auth/platform/{id}`

- Auth: X-API-Key header
- Operation ID: `AuthController_getPlatform`

Retrieve platform information by ID

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/auth/platform/<id> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Platform found

```json
{}
```

**404** Platform not found

---

## Update platform

`PUT /api/v1/auth/platform/{id}`

- Auth: X-API-Key header
- Operation ID: `AuthController_updatePlatform`

Update platform settings

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Platform name |
| `webhookUrl` | string | no | Webhook URL |
| `isActive` | boolean | no | Platform active status |
| `settings` | object | no | Platform settings |
| `scopes` | array of enum ("read:transactions", "write:transactions", "cancel:transactions", "rescind:transactions", "read:customers", "write:customers", "read:templates", "write:templates", "read:disputes", "write:disputes", "submit:evidence", "read:webhooks", "write:webhooks", "read:compliance", "write:compliance", "read:platform", "write:platform", "manage:api-keys", "admin:platform") | no | API scopes granted to this platform |

```json
{
  "name": "string",
  "webhookUrl": "string",
  "isActive": true,
  "settings": {},
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ]
}
```

### Example request

```bash
curl -X PUT https://api-staging.coinbax.com/api/v1/auth/platform/<id> \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "webhookUrl": "string",
  "isActive": true,
  "settings": {},
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ]
}'
```

### Responses

**200** Platform updated successfully

```json
{}
```

**404** Platform not found

---

## Deactivate platform

`DELETE /api/v1/auth/platform/{id}`

- Auth: X-API-Key header
- Operation ID: `AuthController_deactivatePlatform`

Deactivate a platform (soft delete)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Example request

```bash
curl -X DELETE https://api-staging.coinbax.com/api/v1/auth/platform/<id> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**204** Platform deactivated successfully

**404** Platform not found

---

## List all platforms

`GET /api/v1/auth/platforms`

- Auth: X-API-Key header
- Operation ID: `AuthController_listPlatforms`

Get all platforms (admin only)

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/auth/platforms \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Platforms retrieved successfully

```json
[
  {}
]
```

---

## Verify API key

`POST /api/v1/auth/verify`

- Auth: X-API-Key header
- Operation ID: `AuthController_verifyApiKey`

Check if an API key is valid and active

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-api-key` | header | string | yes |  |
| `X-API-Key` | header | string | yes | API key to verify |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/auth/verify \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Verification result

```json
{
  "valid": true,
  "platformId": {},
  "platformName": {},
  "isActive": true
}
```


---

# Controls (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/controls/
> Staging base URL: https://api-staging.coinbax.com

## Verify 2FA code

`POST /api/v1/controls/verify-2fa`

- Auth: X-API-Key header
- Operation ID: `ControlsController_verify2FA`

Verify SMS code sent via TwoFactorAuth control

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |

```json
{}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/controls/verify-2fa \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Responses

**200** Verification result

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "platformId": "550e8400-e29b-41d4-a716-446655440001",
  "userId": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "type": "identity",
  "status": "approved",
  "level": "basic",
  "riskRating": "low",
  "provider": "persona",
  "externalInquiryId": "inq_ABC123",
  "externalSessionToken": "session_token_xyz",
  "metadata": {
    "email": "user@example.com",
    "country": "US"
  },
  "rejectionReason": null,
  "verifiedAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T10:30:00Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

---

## Verify Twilio SMS code

`POST /api/v1/controls/verify-twilio-sms`

- Auth: X-API-Key header
- Operation ID: `ControlsController_verifyTwilioSMS`

Verify SMS code sent via TwilioSMS control using Twilio Verify

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |

```json
{}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/controls/verify-twilio-sms \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Responses

**200** Verification result

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "platformId": "550e8400-e29b-41d4-a716-446655440001",
  "userId": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "type": "identity",
  "status": "approved",
  "level": "basic",
  "riskRating": "low",
  "provider": "persona",
  "externalInquiryId": "inq_ABC123",
  "externalSessionToken": "session_token_xyz",
  "metadata": {
    "email": "user@example.com",
    "country": "US"
  },
  "rejectionReason": null,
  "verifiedAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T10:30:00Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```


---

# Health (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/health/
> Staging base URL: https://api-staging.coinbax.com

Health check and monitoring endpoints

## Complete health check

`GET /api/v1/health`

- Auth: Public (no authentication)
- Operation ID: `HealthController_check`

Returns detailed health status of all system components including database, cache, blockchain, and external services

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/health
```

### Responses

**200** System is healthy

```json
{
  "status": "healthy",
  "timestamp": "2024-10-14T20:30:00.000Z",
  "version": "0.1.0",
  "uptime": 3600,
  "database": {
    "status": "up",
    "responseTime": 12,
    "details": {
      "version": "14.2",
      "connections": 10
    },
    "error": "Connection timeout"
  },
  "cache": {
    "status": "up",
    "responseTime": 12,
    "details": {
      "version": "14.2",
      "connections": 10
    },
    "error": "Connection timeout"
  },
  "blockchain": {
    "status": "up",
    "responseTime": 12,
    "details": {
      "version": "14.2",
      "connections": 10
    },
    "error": "Connection timeout"
  },
  "riskService": {
    "status": "up",
    "responseTime": 12,
    "details": {
      "version": "14.2",
      "connections": 10
    },
    "error": "Connection timeout"
  },
  "memory": {
    "total": 16777216000,
    "free": 8388608000,
    "used": 8388608000,
    "usedPercent": 50
  },
  "process": {
    "pid": 12345,
    "memoryUsage": 150000000,
    "cpuUsage": 5.5
  }
}
```

**503** System is unhealthy

---

## Liveness probe

`GET /api/v1/health/live`

- Auth: Public (no authentication)
- Operation ID: `HealthController_liveness`

Kubernetes liveness probe - checks if the application is running. Returns 200 if alive, 503 if dead.

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/health/live
```

### Responses

**200** Application is alive

```json
{
  "status": "alive",
  "timestamp": "2024-10-14T20:30:00.000Z",
  "uptime": 3600
}
```

**503** Application is not responding

---

## Readiness probe

`GET /api/v1/health/ready`

- Auth: Public (no authentication)
- Operation ID: `HealthController_readiness`

Kubernetes readiness probe - checks if application can accept traffic. Validates critical dependencies.

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/health/ready
```

### Responses

**200** Application is ready to accept traffic

```json
{
  "status": "ready",
  "timestamp": "2024-10-14T20:30:00.000Z",
  "dependencies": {
    "database": "up",
    "cache": "up"
  }
}
```

**503** Application is not ready

---

## Test Sentry integration

`GET /api/v1/sentry-test`

- Auth: Public (no authentication)
- Operation ID: `SentryTestController_testSentry`

Triggers various types of Sentry events for testing. Use query parameter "type" to select test type: error, log, or span.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `type` | query | enum ("error", "log", "span") | no | Type of Sentry test to run |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/sentry-test
```

### Responses

**200** Test completed successfully (log or span)

**500** Test error thrown (error type)


---

# JWKS (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/jwks/
> Staging base URL: https://api-staging.coinbax.com

## Get JSON Web Key Set

`GET /.well-known/jwks.json`

- Auth: Public (no authentication)
- Operation ID: `JwksController_getJwks`

Returns the public keys in JWKS format for JWT signature verification. Used by external services (e.g., Jack Henry jXchange) to verify signed JWTs.

### Example request

```bash
curl https://api-staging.coinbax.com/.well-known/jwks.json
```

### Responses

**200** JWKS containing public keys

```json
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "coinbax-jh-key-001",
      "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
      "e": "AQAB"
    }
  ]
}
```


---

# OAuth 2.0 (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/oauth-2-0/
> Staging base URL: https://api-staging.coinbax.com

## List OAuth clients

`GET /api/v1/oauth/clients`

- Auth: Bearer token
- Operation ID: `OAuthController_listClients`

List all OAuth clients for a platform

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `platformId` | query | string | yes |  |
| `workspaceId` | query | string | yes |  |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/oauth/clients?platformId=<platformId>&workspaceId=<workspaceId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** List of OAuth clients

```json
[
  {
    "clientId": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
    "name": "My Integration App",
    "description": "Third-party integration for transaction processing",
    "scopes": [
      "read:transactions",
      "write:transactions"
    ],
    "isActive": true,
    "createdAt": "2026-02-24T12:00:00Z",
    "lastUsedAt": "2026-02-24T14:30:00Z"
  }
]
```

---

## Create OAuth client

`POST /api/v1/oauth/clients`

- Auth: Bearer token
- Operation ID: `OAuthController_createClient`

Register a new OAuth client for a platform. The client secret is only shown once.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `platformId` | string | yes | Platform ID the OAuth client belongs to |
| `workspaceId` | string | no | Optional workspace ID for workspace-scoped clients |
| `name` | string | yes | Name of the OAuth client |
| `description` | string | no | Description of the OAuth client |
| `scopes` | array of string | yes | List of scopes the client is authorized for |
| `grantTypes` | array of string | no | Grant types allowed for this client |
| `redirectUris` | array of string | no | Redirect URIs for authorization code flow (future use) |

```json
{
  "platformId": "550e8400-e29b-41d4-a716-446655440000",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440001",
  "name": "My Integration App",
  "description": "Third-party integration for transaction processing",
  "scopes": [
    "read:transactions",
    "write:transactions"
  ],
  "grantTypes": [
    "client_credentials"
  ],
  "redirectUris": [
    "https://example.com/callback"
  ]
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/oauth/clients \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "platformId": "550e8400-e29b-41d4-a716-446655440000",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440001",
  "name": "My Integration App",
  "description": "Third-party integration for transaction processing",
  "scopes": [
    "read:transactions",
    "write:transactions"
  ],
  "grantTypes": [
    "client_credentials"
  ],
  "redirectUris": [
    "https://example.com/callback"
  ]
}'
```

### Responses

**201** OAuth client created successfully

```json
{
  "clientId": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
  "clientSecret": "coinbax_secret_x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q0",
  "name": "My Integration App",
  "scopes": [
    "read:transactions",
    "write:transactions"
  ],
  "createdAt": "2026-02-24T12:00:00Z",
  "warning": "Store the client secret securely. It will not be shown again."
}
```

**400** Invalid request or invalid scopes

---

## Get OAuth client details

`GET /api/v1/oauth/clients/{clientId}`

- Auth: Bearer token
- Operation ID: `OAuthController_getClient`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes |  |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/oauth/clients/<clientId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** OAuth client details

```json
{
  "clientId": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
  "name": "My Integration App",
  "description": "Third-party integration for transaction processing",
  "scopes": [
    "read:transactions",
    "write:transactions"
  ],
  "isActive": true,
  "createdAt": "2026-02-24T12:00:00Z",
  "lastUsedAt": "2026-02-24T14:30:00Z"
}
```

**404** Client not found

---

## Delete OAuth client

`DELETE /api/v1/oauth/clients/{clientId}`

- Auth: Bearer token
- Operation ID: `OAuthController_deleteClient`

Permanently delete an OAuth client and all its tokens

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes |  |

### Example request

```bash
curl -X DELETE https://api-staging.coinbax.com/api/v1/oauth/clients/<clientId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**204** OAuth client deleted successfully

**404** Client not found

---

## Update OAuth client

`PATCH /api/v1/oauth/clients/{clientId}`

- Auth: Bearer token
- Operation ID: `OAuthController_updateClient`

Update OAuth client settings. Deactivating a client will revoke all its tokens.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Name of the OAuth client |
| `description` | string | no | Description of the OAuth client |
| `scopes` | array of string | no | Updated list of scopes |
| `isActive` | boolean | no | Whether the client is active |

```json
{
  "name": "Updated Integration App",
  "description": "Updated description",
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ],
  "isActive": true
}
```

### Example request

```bash
curl -X PATCH https://api-staging.coinbax.com/api/v1/oauth/clients/<clientId> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Updated Integration App",
  "description": "Updated description",
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ],
  "isActive": true
}'
```

### Responses

**200** OAuth client updated successfully

```json
{
  "clientId": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
  "name": "My Integration App",
  "description": "Third-party integration for transaction processing",
  "scopes": [
    "read:transactions",
    "write:transactions"
  ],
  "isActive": true,
  "createdAt": "2026-02-24T12:00:00Z",
  "lastUsedAt": "2026-02-24T14:30:00Z"
}
```

**404** Client not found

---

## Revoke all client tokens

`POST /api/v1/oauth/clients/{clientId}/revoke-all-tokens`

- Auth: Bearer token
- Operation ID: `OAuthController_revokeAllClientTokens`

Revoke all active access tokens for a client

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes |  |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/oauth/clients/<clientId>/revoke-all-tokens \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** All tokens revoked

**404** Client not found

---

## Get client token statistics

`GET /api/v1/oauth/clients/{clientId}/stats`

- Auth: Bearer token
- Operation ID: `OAuthController_getClientStats`

Get token usage statistics for a client

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes |  |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/oauth/clients/<clientId>/stats \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Token statistics

**404** Client not found

---

## Revoke access token

`POST /api/v1/oauth/revoke`

- Auth: Bearer token
- Operation ID: `OAuthController_revoke`

Revoke an active access token by its JWT ID (jti)

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token_jti` | string | yes | JWT ID (jti) of the token to revoke |

```json
{
  "token_jti": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/oauth/revoke \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "token_jti": "550e8400-e29b-41d4-a716-446655440000"
}'
```

### Responses

**200** Token revoked successfully

**404** Token not found

---

## List available OAuth scopes

`GET /api/v1/oauth/scopes`

- Auth: Public (no authentication)
- Operation ID: `OAuthController_listScopes`

Get the catalog of available OAuth scopes that can be assigned to clients

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/oauth/scopes
```

### Responses

**200** List of available scopes

```json
[
  {}
]
```

---

## OAuth 2.0 Token Endpoint

`POST /api/v1/oauth/token`

- Auth: Public (no authentication)
- Operation ID: `OAuthController_token`

Generate access token using Client Credentials flow (RFC 6749)

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `grant_type` | enum ("client_credentials") | yes | OAuth 2.0 grant type |
| `client_id` | string | yes | OAuth client ID |
| `client_secret` | string | yes | OAuth client secret |
| `scope` | string | no | Space-separated list of requested scopes (optional, defaults to all client scopes) |

```json
{
  "grant_type": "client_credentials",
  "client_id": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
  "client_secret": "coinbax_secret_x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q0",
  "scope": "read:transactions write:transactions"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
  "grant_type": "client_credentials",
  "client_id": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
  "client_secret": "coinbax_secret_x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q0",
  "scope": "read:transactions write:transactions"
}'
```

### Responses

**200** Access token generated successfully

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:transactions write:transactions"
}
```

**400** Invalid request or unsupported grant type

**401** Invalid client credentials


---

# Platform (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/platform/
> Staging base URL: https://api-staging.coinbax.com

## Get platform configuration

`GET /api/v1/platform/config`

- Auth: Bearer token
- Operation ID: `PlatformController_getConfig`

Returns contract deployments, templates, and settings for the authenticated platform

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `network` | query | string | no | Filter by specific network (e.g., base, base-sepolia) |
| `includeTemplate` | query | boolean | no | Include full template details (default: true) |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/platform/config \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Platform configuration returned successfully

```json
{
  "platform": {
    "id": "string",
    "name": "string"
  },
  "contracts": [
    {
      "network": "string",
      "address": "string",
      "isShared": true,
      "templateId": "string",
      "template": {}
    }
  ]
}
```

**401** Invalid or missing OAuth token

**403** Insufficient scopes


---

# Transaction Stream (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/transaction-stream/
> Staging base URL: https://api-staging.coinbax.com

## Subscribe to real-time transaction updates

`GET /api/v1/transactions/{id}/stream`

- Auth: X-API-Key header
- Operation ID: `TransactionStreamController_streamUpdates`

Opens an SSE stream for real-time transaction and control execution updates

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Example request

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

### Responses

**200** SSE stream opened successfully

**404** Transaction not found


---

# Transactions (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/transactions/
> Staging base URL: https://api-staging.coinbax.com

Payment operations and lifecycle management

## List transactions with filters

`GET /api/v1/transactions`

- Auth: X-API-Key header
- Operation ID: `TransactionController_findAll`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | number | no | Page number |
| `limit` | query | number | no | Items per page |
| `status` | query | enum ("pending", "risk_review", "pending_user_action", "escrowed", "in_review", "disputed", "completed", "refunded", "failed", "rescinded") | no | Filter by status |
| `fromAddress` | query | string | no | Filter by sender blockchain address |
| `toAddress` | query | string | no | Filter by receiver blockchain address |
| `dateFrom` | query | string | no | Filter by date from (ISO 8601) |
| `dateTo` | query | string | no | Filter by date to (ISO 8601) |
| `customerId` | query | string | no | Filter by customer ID |
| `walletAddress` | query | string | no | Filter by wallet address (matches fromAddress OR toAddress) |

### Example request

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

### Responses

**200** List of transactions

---

## Create a new transaction

`POST /api/v1/transactions`

- Auth: X-API-Key header
- Operation ID: `TransactionController_create`

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fromAddress` | string | yes | Sender blockchain address |
| `toAddress` | string | yes | Receiver blockchain address |
| `amount` | number | yes | Transaction amount (minimum 0.01, maximum 1,000,000) |
| `currency` | enum ("USDC", "USDT", "ETH", "MockUSDC", "USDG") | no | Currency type |
| `blockchainNetwork` | enum ("ethereum", "base", "solana", "optimism", "arbitrum", "base-sepolia", "ethereum-sepolia", "optimism-sepolia", "arbitrum-sepolia", "solana-devnet", "solana-testnet") | no | Blockchain network. Defaults to the environment's Base network when omitted ('base' on production, 'base-sepolia' on local/staging). Mainnet names sent to local/staging are coerced to their testnet counterpart (e.g. base → base-sepolia); testnet names sent to production are rejected with TESTNET_NOT_ALLOWED_IN_PRODUCTION. |
| `orchestrationType` | enum ("raw", "coinbax") | no | Orchestration type: raw (direct blockchain) or coinbax (smart contract escrow) |
| `templateId` | string (uuid) | no | Template ID from coinbax-library. The template will be fetched from the library service. |
| `contractTemplateId` | string (uuid) | no | Contract template ID (alias for templateId, for backward compatibility) |
| `template` | object | no | Complete template data embedded in request (optional, prefer using templateId instead) |
| `metadata` | object | no | Additional metadata about the transaction |
| `billingConfig` | object | no | Billing configuration from workspace (passed by coinbax-core) |
| `quoteId` | string (uuid) | no | FeeQuote id from a prior /transactions/quote call. Required when the workspace has BILLING_ENABLED=true (Phase 1 cutover). |
| `signerType` | enum ("custodial", "external_wallet") | no | Signer type: custodial (Coinbax signs) or external_wallet (User signs via MetaMask) |
| `customerId` | string | no | Customer ID for external wallet transactions (Transmitter users) |
| `idempotencyKey` | string | no | Idempotency key to prevent duplicate transaction creation. If provided, a transaction with the same key will return the existing transaction instead of creating a new one. |

```json
{
  "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "amount": 100.5,
  "currency": "USDC",
  "blockchainNetwork": "base",
  "orchestrationType": "raw",
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "contractTemplateId": "550e8400-e29b-41d4-a716-446655440000",
  "template": {
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "templateName": "2FA Escrow",
    "templateVersion": "1.0.0",
    "controls": [
      {
        "id": "control-123",
        "type": "TwoFactorAuth",
        "name": "Two-Factor Authentication",
        "executionPhase": "PRE_ESCROW",
        "executionOrder": 1,
        "config": {
          "method": "sms",
          "phoneNumber": "+1234567890"
        }
      }
    ]
  },
  "metadata": {
    "orderId": "order_789",
    "productName": "Premium Widget"
  },
  "billingConfig": {
    "feeType": "percentage",
    "feePercentage": 30,
    "feeWalletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "currency": "USDC",
    "isActive": true
  },
  "quoteId": "550e8400-e29b-41d4-a716-446655440000",
  "signerType": "custodial",
  "customerId": "cust_abc123",
  "idempotencyKey": "tx_unique_key_12345"
}
```

### Example request

```bash
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": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "amount": 100.5,
  "currency": "USDC",
  "blockchainNetwork": "base",
  "orchestrationType": "raw",
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "contractTemplateId": "550e8400-e29b-41d4-a716-446655440000",
  "template": {
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "templateName": "2FA Escrow",
    "templateVersion": "1.0.0",
    "controls": [
      {
        "id": "control-123",
        "type": "TwoFactorAuth",
        "name": "Two-Factor Authentication",
        "executionPhase": "PRE_ESCROW",
        "executionOrder": 1,
        "config": {
          "method": "sms",
          "phoneNumber": "+1234567890"
        }
      }
    ]
  },
  "metadata": {
    "orderId": "order_789",
    "productName": "Premium Widget"
  },
  "billingConfig": {
    "feeType": "percentage",
    "feePercentage": 30,
    "feeWalletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "currency": "USDC",
    "isActive": true
  },
  "quoteId": "550e8400-e29b-41d4-a716-446655440000",
  "signerType": "custodial",
  "customerId": "cust_abc123",
  "idempotencyKey": "tx_unique_key_12345"
}'
```

### Responses

**201** Transaction created successfully

```json
{
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
```

**409** Duplicate transaction detected within time window

**429** Transaction rate limit exceeded (max 10/minute per sender)

---

## Money-at-risk: count + age of funds stuck in non-terminal states

`GET /api/v1/transactions/at-risk`

- Auth: X-API-Key header
- Operation ID: `TransactionController_getAtRiskStatistics`

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/transactions/at-risk \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Per-status (escrowed/in_review/pending_user_action/disputed) count, total amount, oldest age, and >24h/>72h aged counts

---

## List transaction batches with filters

`GET /api/v1/transactions/batch`

- Auth: X-API-Key header
- Operation ID: `TransactionController_findAllBatches`

Returns a paginated list of multi-recipient batches scoped to the calling platform. Legs are not embedded — fetch a single batch via GET /transactions/batch/:id for that.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | number | no | Page number |
| `limit` | query | number | no | Items per page |
| `status` | query | enum ("pending_user_action", "submitted", "completed", "failed") | no | Filter by batch status |
| `fromAddress` | query | string | no | Filter by sender blockchain address |
| `dateFrom` | query | string | no | Filter by date from (ISO 8601) |
| `dateTo` | query | string | no | Filter by date to (ISO 8601) |
| `customerId` | query | string | no | Filter by customer ID |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/transactions/batch \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Paginated list of batches

---

## Create a multi-recipient transaction batch

`POST /api/v1/transactions/batch`

- Auth: X-API-Key header
- Operation ID: `TransactionController_createBatch`

Creates a parent batch row plus one Transaction leg per recipient in a single DB transaction. The client (e.g., SafeSend) then signs and submits `WorkspaceEscrow.batchCreateEscrow` with each leg's UUID as the on-chain `transactionId`. Per-leg `EscrowCreated` events flow through the existing event monitor and transition each leg from PENDING_USER_ACTION to ESCROWED individually.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fromAddress` | string | yes | Sender blockchain address (one signer for the whole batch). |
| `legs` | array of CreateBatchLegDto | yes | Per-recipient legs (1..MAX_BATCH_LEGS). |
| `currency` | enum ("USDC", "USDT", "ETH", "MockUSDC", "USDG") | no | Currency type — shared by every leg in the batch. |
| `blockchainNetwork` | string | no | Blockchain network. The set of accepted values mirrors `CreateTransactionDto.blockchainNetwork`, including the env-aware default ('base' on production, 'base-sepolia' on local/staging), non-prod coercion of mainnet names, and production rejection of testnet names. |
| `orchestrationType` | enum ("raw", "coinbax") | no | Orchestration type for every leg. |
| `signerType` | enum ("custodial", "external_wallet") | no | Signer type. Must be `external_wallet` in B1 — custodial batch sends are not supported in this phase. |
| `templateId` | string (uuid) | no | Template ID from coinbax-library. Stored on the batch in B1; control execution against the template is wired in B2. |
| `customerId` | string | no | Customer ID for external-wallet flows (Transmitter, SafeSend). |
| `idempotencyKey` | string | no | Idempotency key — if provided, an existing batch with the same key is returned instead of creating a new one. |
| `metadata` | object | no | Batch-level metadata (distinct from per-leg metadata). |
| `template` | object | no | Embedded template (alternative to `templateId`, deprecated for consistency with `CreateTransactionDto`). |

```json
{
  "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "legs": [
    {
      "toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "amount": 100.5,
      "metadata": {
        "recipientLabel": "Alice",
        "orderId": "order_789"
      }
    }
  ],
  "currency": "USDC",
  "blockchainNetwork": "base",
  "orchestrationType": "raw",
  "signerType": "external_wallet",
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "cust_abc123",
  "idempotencyKey": "batch_unique_key_12345",
  "metadata": {
    "source": "safesend",
    "uiVersion": "1.2.3"
  },
  "template": {
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "templateName": "2FA Escrow",
    "templateVersion": "1.0.0",
    "controls": [
      {
        "id": "control-123",
        "type": "TimeDelay",
        "name": "Payment Hold Period",
        "executionPhase": "PRE_ESCROW",
        "executionOrder": 1,
        "config": {
          "delayMinutes": 5
        },
        "isRequired": true,
        "isActive": true
      }
    ]
  }
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/batch \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "legs": [
    {
      "toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "amount": 100.5,
      "metadata": {
        "recipientLabel": "Alice",
        "orderId": "order_789"
      }
    }
  ],
  "currency": "USDC",
  "blockchainNetwork": "base",
  "orchestrationType": "raw",
  "signerType": "external_wallet",
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "cust_abc123",
  "idempotencyKey": "batch_unique_key_12345",
  "metadata": {
    "source": "safesend",
    "uiVersion": "1.2.3"
  },
  "template": {
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "templateName": "2FA Escrow",
    "templateVersion": "1.0.0",
    "controls": [
      {
        "id": "control-123",
        "type": "TimeDelay",
        "name": "Payment Hold Period",
        "executionPhase": "PRE_ESCROW",
        "executionOrder": 1,
        "config": {
          "delayMinutes": 5
        },
        "isRequired": true,
        "isActive": true
      }
    ]
  }
}'
```

### Responses

**201** Batch created successfully (legs included in `legs`)

```json
{}
```

**400** Invalid request — empty/oversized `legs`, malformed addresses, unsupported `signerType`, or template validation failure

**403** Customer approval required or sender not approved

**429** Transaction rate limit exceeded

---

## Get a transaction batch by ID

`GET /api/v1/transactions/batch/{id}`

- Auth: X-API-Key header
- Operation ID: `TransactionController_findBatch`

Returns the parent batch row plus all child Transaction legs. Each leg carries its own status, escrowId, and per-recipient metadata; per-leg listing of just the legs is also reachable via GET /transactions?batchId=…

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Example request

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

### Responses

**200** Batch details with legs

```json
{}
```

**404** Batch not found

---

## Manually cancel an unsubmitted batch

`POST /api/v1/transactions/batch/{id}/cancel`

- Auth: X-API-Key header
- Operation ID: `TransactionController_cancelBatch`

Marks a batch FAILED and propagates the same status to every leg. Allowed only while the batch is in `pending_user_action` (the user hasn't signed `batchCreateEscrow` yet, or is parked awaiting verification). Once the on-chain tx is in flight, use per-leg refund/dispute endpoints instead. Idempotent on already-FAILED batches. Fires a `transaction.batch.failed` webhook on success.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | no | Human-readable reason recorded on the batch metadata. Surfaces in audit logs and the cancel webhook payload. Truncated at 500 chars. |

```json
{
  "reason": "Sender closed the tab before signing batchCreateEscrow"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/batch/<id>/cancel \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Sender closed the tab before signing batchCreateEscrow"
}'
```

### Responses

**200** Batch cancelled (or was already FAILED — idempotent)

```json
{}
```

**400** Batch is in a state that cannot be cancelled (submitted / completed)

**404** Batch not found

---

## Record the on-chain batchCreateEscrow transaction hash

`POST /api/v1/transactions/batch/{id}/submit-escrow-hash`

- Auth: X-API-Key header
- Operation ID: `TransactionController_submitBatchEscrowHash`

Stores the shared on-chain transaction hash on the batch + every leg, and advances the batch to `submitted`. Per-leg `EscrowCreated` events drive each leg from `pending_user_action` to `escrowed` independently via the existing event monitor.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transactionHash` | string | yes | On-chain transaction hash for the `batchCreateEscrow` call. Shared by every leg in the batch (one signature, one tx). |

```json
{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/batch/<id>/submit-escrow-hash \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}'
```

### Responses

**200** Hash recorded, batch advanced to submitted

```json
{}
```

**400** Batch is in a non-submittable state (already terminal, or still awaiting verification), or the request is for a custodial batch

**404** Batch not found

---

## Verify a 2FA code against a pending batch control

`POST /api/v1/transactions/batch/{id}/verify-2fa`

- Auth: X-API-Key header
- Operation ID: `TransactionController_verifyBatch2FA`

Accepts the verification code the sender received and clears the batch's `awaitingControlVerification` flag once every PRE_ESCROW verification control resolves.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes | 6-digit verification code sent via SMS |

```json
{
  "code": "123456"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/batch/<id>/verify-2fa \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "123456"
}'
```

### Responses

**200** Code accepted, batch updated

```json
{}
```

**400** Batch not awaiting verification, no pending 2FA control, or invalid/expired code

**404** Batch not found

---

## Preview platform fee for a transaction

`POST /api/v1/transactions/fee-preview`

- Auth: X-API-Key header
- Operation ID: `TransactionController_previewFee`

Calculate and preview the platform fee before creating a transaction

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | number | yes | The proposed transaction amount |
| `billingConfig` | object | yes | Billing configuration from workspace |

```json
{
  "amount": 100.5,
  "billingConfig": {
    "feeType": "percentage",
    "feePercentage": 30,
    "fixedFeeAmount": 1,
    "tieredFees": [
      {
        "minAmount": 0,
        "maxAmount": 1000,
        "feePercentage": 30
      }
    ],
    "feeWalletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "currency": "USDC",
    "isActive": true
  }
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/fee-preview \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 100.5,
  "billingConfig": {
    "feeType": "percentage",
    "feePercentage": 30,
    "fixedFeeAmount": 1,
    "tieredFees": [
      {
        "minAmount": 0,
        "maxAmount": 1000,
        "feePercentage": 30
      }
    ],
    "feeWalletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "currency": "USDC",
    "isActive": true
  }
}'
```

### Responses

**200** Fee preview calculated successfully

```json
{
  "originalAmount": 100.5,
  "feeAmount": 0.3015,
  "netAmount": 100.1985,
  "feeType": "percentage",
  "feeBasisPoints": 30,
  "feePercentageDisplay": "0.30%",
  "feeWalletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "billingActive": true
}
```

---

## Create a fee quote for a pending transaction

`POST /api/v1/transactions/quote`

- Auth: X-API-Key header
- Operation ID: `TransactionController_createQuote`

Returns a 120-second-TTL quote with platform fee, workspace fee, gas pass-through (if applicable), and total charged. Pass the returned `quoteId` to `POST /transactions` to lock the rate.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amountUsd` | string | yes | USD principal amount |
| `asset` | string | yes |  |
| `network` | string | yes | Canonical network identifier |

```json
{
  "amountUsd": "1000.00",
  "asset": "USDC",
  "network": "base"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/quote \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amountUsd": "1000.00",
  "asset": "USDC",
  "network": "base"
}'
```

### Responses

**200** Quote created successfully

```json
{
  "quoteId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "expiresAt": "2026-01-15T12:00:00.000Z",
  "amountUsd": "1000.00",
  "platformFeeUsd": "2.500000",
  "workspaceFeeUsd": "5.000000",
  "gasPassThroughUsd": null,
  "totalOnTopUsd": "7.500000",
  "totalChargedUsd": "1007.500000",
  "gasCapExceeded": false
}
```

**404** Workspace has no ACTIVE PricingPlan / WorkspaceFeeSchedule. Operator intervention required.

**422** Gas-cap exceeded and PricingPlan.onGasCapBreach=BLOCK. The caller can retry later if gas drops.

**503** Transient: gas oracle / FX / coinbax-core unreachable. Retry.

---

## Get transaction statistics

`GET /api/v1/transactions/stats`

- Auth: X-API-Key header
- Operation ID: `TransactionController_getStatistics`

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/transactions/stats \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Transaction statistics

---

## Get sanitized template + controls config for a template ID

`GET /api/v1/transactions/template-config`

- Auth: X-API-Key header
- Operation ID: `TransactionController_getTemplateConfig`

Returns public-safe summaries of each active control on a template. Used by pre-confirmation surfaces (e.g. SafeSend) to render "What protects your send" panels and to enforce client-side AmountLimit min/max. Sanitized: only a hand-picked subset of each control config is returned — policy/implementation fields are NOT exposed.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `templateId` | query | string | yes |  |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/transactions/template-config?templateId=<templateId> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Template config retrieved

```json
{
  "templateId": "a1b2c3d4-e5f6-4a5b-8c9d-1234567890ab",
  "templateName": "Transmitter P2P",
  "templateVersion": "1.0.0",
  "controls": [
    {
      "type": "AmountLimit",
      "phase": "PRE_ESCROW",
      "name": "Amount Limit Check",
      "isRequired": true,
      "minAmount": 1,
      "maxAmount": 1000000,
      "currency": "USD",
      "delayAmount": 24,
      "delayUnit": "hours",
      "allowSenderRescind": true,
      "userConfigurable": true,
      "options": [
        "5m",
        "30m",
        "24h",
        "48h",
        "7d"
      ],
      "sanctionsLists": [
        "OFAC",
        "SDN",
        "EU"
      ],
      "checksSender": true,
      "checksRecipient": true,
      "verificationRequired": true
    }
  ]
}
```

**404** Template not found

---

## Get transaction by ID

`GET /api/v1/transactions/{id}`

- Auth: X-API-Key header
- Operation ID: `TransactionController_findOne`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Example request

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

### Responses

**200** Transaction details

```json
{
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
```

**404** Transaction not found

---

## Authorize release of an external-wallet escrow

`POST /api/v1/transactions/{id}/authorize-release`

- Auth: X-API-Key header
- Operation ID: `TransactionController_authorizeRelease`

Runs the PRE_RELEASE controls and records the aggregate result on-chain for an external-wallet (SafeSend) COINBAX escrow, so the sender wallet (releaseEarly / releaseAfterDelay) can release without the escrow's PRE_RELEASE gate reverting. Call this immediately BEFORE the on-chain release write. An early (pre-window) release waives the time-delay hold; a required non-time control failure auto-rejects the escrow and refunds the sender (do not then attempt an on-chain release).

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `early` | boolean | no | Advisory hint that the sender intends an early (pre-window) release. The server authoritatively infers early vs after-delay from the escrow release time and ignores this value for the decision. |

```json
{
  "early": true
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/<id>/authorize-release \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "early": true
}'
```

### Responses

**200** Release authorized (PRE_RELEASE attested Passed), or the escrow was rejected + refunded because a required control failed (see `rejected`).

**400** Not an external-wallet COINBAX escrow, not in ESCROWED status, or missing on-chain escrow id

**404** Transaction not found

---

## Get bit execution status for transaction

`GET /api/v1/transactions/{id}/bit-status`

- Auth: X-API-Key header
- Operation ID: `TransactionController_getBitStatus`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/transactions/<id>/bit-status \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Bit execution status retrieved successfully

```json
{
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "awaitingVerification": false,
  "controls": [
    {
      "controlId": "control-uuid",
      "controlType": "TimeDelay",
      "phase": "PRE_ESCROW",
      "success": true,
      "isRequired": true,
      "durationMs": 125,
      "data": {},
      "executedAt": "2026-01-15T12:00:00.000Z"
    }
  ],
  "success": true,
  "nextAction": "verify_2fa",
  "message": "All controls executed successfully"
}
```

**404** Transaction not found

---

## Cancel pre-escrow transaction the user never signed for

`POST /api/v1/transactions/{id}/cancel`

- Auth: X-API-Key header
- Operation ID: `TransactionController_cancelPending`

Marks a transaction in PENDING_USER_ACTION as FAILED with userCancelled=true. No on-chain action — funds were never escrowed. Use this when the user rejects the wallet popup and does not intend to retry; rejects with 400 if the transaction has already advanced to ESCROWED (use /refund or /rescind instead) or is already terminal.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | no | Optional human-readable reason for the cancellation. Surfaced in the transaction.failed webhook and stored on `metadata.cancelReason`. |

```json
{
  "reason": "User dismissed pending tx from SafeSend Active tab"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/<id>/cancel \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "User dismissed pending tx from SafeSend Active tab"
}'
```

### Responses

**200** Transaction cancelled successfully

```json
{
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
```

**400** Transaction not in PENDING_USER_ACTION, or already has an on-chain escrow address

**404** Transaction not found

---

## Complete transaction and release funds

`POST /api/v1/transactions/{id}/complete`

- Auth: X-API-Key header
- Operation ID: `TransactionController_complete`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | string | no | Optional completion note |

```json
{
  "note": "Service delivered successfully"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/<id>/complete \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Service delivered successfully"
}'
```

### Responses

**200** Transaction completed successfully

```json
{
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
```

**400** Invalid transaction state for completion

---

## Refund transaction

`POST /api/v1/transactions/{id}/refund`

- Auth: X-API-Key header
- Operation ID: `TransactionController_refund`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | yes | Reason for refund |

```json
{
  "reason": "Customer request - item not as described"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/<id>/refund \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Customer request - item not as described"
}'
```

### Responses

**200** Transaction refunded successfully

```json
{
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
```

**400** Invalid transaction state for refund

---

## Rescind transaction during hold period (sender only)

`POST /api/v1/transactions/{id}/rescind`

- Auth: X-API-Key header
- Operation ID: `TransactionController_rescind`

Allows the sender to cancel a transaction during the Payment Hold Period and have funds returned to their wallet. Only available if the TimeDelay control has allowSenderRescind enabled.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | no | Reason for rescinding the transaction (required if control config has rescindRequiresReason: true) |
| `senderWallet` | string | yes | Sender wallet address for authorization verification |

```json
{
  "reason": "Changed my mind about the purchase",
  "senderWallet": "0x1234567890abcdef1234567890abcdef12345678"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/<id>/rescind \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Changed my mind about the purchase",
  "senderWallet": "0x1234567890abcdef1234567890abcdef12345678"
}'
```

### Responses

**200** Transaction rescinded successfully, funds returned to sender

```json
{
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
```

**400** Transaction cannot be rescinded (not in ESCROWED status, rescind not enabled, or rescind window expired)

**403** Only the sender can rescind a transaction

**404** Transaction not found

---

## Resend 2FA verification code

`POST /api/v1/transactions/{id}/resend-2fa`

- Auth: X-API-Key header
- Operation ID: `TransactionController_resend2FA`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/<id>/resend-2fa \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** 2FA code resent successfully

```json
{
  "message": "2FA code resent successfully",
  "expiresIn": 300
}
```

**400** Transaction not awaiting 2FA verification

**404** Transaction not found

---

## Retry a failed bit execution

`POST /api/v1/transactions/{id}/retry-bit/{bitId}`

- Auth: X-API-Key header
- Operation ID: `TransactionController_retryBit`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `bitId` | path | string | yes |  |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/<id>/retry-bit/<bitId> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Bit execution retried successfully

```json
{
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
```

**400** Invalid bit ID or bit cannot be retried

**404** Transaction or bit not found

---

## Submit escrow transaction hash for external wallet (Transmitter) transactions

`POST /api/v1/transactions/{id}/submit-escrow-hash`

- Auth: X-API-Key header
- Operation ID: `TransactionController_submitEscrowHash`

After the user deposits USDC to the escrow contract via MetaMask, submit the transaction hash and escrow ID to confirm the escrow was created

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transactionHash` | string | yes | Blockchain transaction hash from user wallet escrow deposit |
| `escrowId` | string | no | Escrow ID returned by the smart contract (optional - will be detected from blockchain events if not provided) |

```json
{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "escrowId": "0x9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/<id>/submit-escrow-hash \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "escrowId": "0x9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef"
}'
```

### Responses

**200** Escrow hash submitted and verified successfully

```json
{
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
```

**400** Invalid transaction state or escrow verification failed

**404** Transaction not found

---

## Submit blockchain transaction hash for RAW transaction

`POST /api/v1/transactions/{id}/submit-hash`

- Auth: X-API-Key header
- Operation ID: `TransactionController_submitTransactionHash`

After sending USDC from your wallet, submit the transaction hash to complete the transaction

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transactionHash` | string | yes | Blockchain transaction hash from user wallet |

```json
{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/<id>/submit-hash \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}'
```

### Responses

**200** Transaction hash submitted and verified successfully

```json
{
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
```

**400** Invalid transaction state or hash verification failed

**404** Transaction not found

---

## Verify 2FA code for transaction

`POST /api/v1/transactions/{id}/verify-2fa`

- Auth: X-API-Key header
- Operation ID: `TransactionController_verify2FA`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes | 6-digit verification code sent via SMS |

```json
{
  "code": "123456"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/<id>/verify-2fa \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "123456"
}'
```

### Responses

**200** 2FA verified successfully, transaction can proceed

```json
{
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
```

**400** Invalid or expired verification code

**404** Transaction not found


---

# Verification (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/verification/
> Staging base URL: https://api-staging.coinbax.com

## Get verification info for a transaction (public)

`GET /api/v1/verify/{transactionId}`

- Auth: Public (no authentication)
- Operation ID: `VerificationController_getVerificationInfo`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `transactionId` | path | string | yes | Transaction UUID from SMS link |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/verify/<transactionId>
```

### Responses

**200** Verification info returned

**404** Transaction not found

---

## Resend verification code (public)

`POST /api/v1/verify/{transactionId}/resend`

- Auth: Public (no authentication)
- Operation ID: `VerificationController_resendCode`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `transactionId` | path | string | yes | Transaction UUID |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/verify/<transactionId>/resend
```

### Responses

**200** Code resent successfully

**429** Rate limited

---

## Verify SMS code (public)

`POST /api/v1/verify/{transactionId}/verify`

- Auth: Public (no authentication)
- Operation ID: `VerificationController_verifyCode`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `transactionId` | path | string | yes | Transaction UUID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |

```json
{}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/verify/<transactionId>/verify \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Responses

**200** Code verified successfully

**400** Invalid code

**404** Transaction not found


---

# compliance (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/compliance/
> Staging base URL: https://api-staging.coinbax.com

## Create a new verification request

`POST /api/v1/api/v1/compliance/verifications`

- Auth: X-API-Key header
- Operation ID: `ComplianceController_createVerification`

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | string | yes | User ID to verify |
| `type` | enum ("identity", "document", "address", "phone", "email") | yes | Type of verification to perform |
| `metadata` | object | no | Additional metadata for verification |

```json
{
  "userId": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "type": "identity",
  "metadata": {
    "email": "user@example.com",
    "country": "US"
  }
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/api/v1/compliance/verifications \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "type": "identity",
  "metadata": {
    "email": "user@example.com",
    "country": "US"
  }
}'
```

### Responses

**201** Verification created successfully

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "platformId": "550e8400-e29b-41d4-a716-446655440001",
  "userId": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "type": "identity",
  "status": "approved",
  "level": "basic",
  "riskRating": "low",
  "provider": "persona",
  "externalInquiryId": "inq_ABC123",
  "externalSessionToken": "session_token_xyz",
  "metadata": {
    "email": "user@example.com",
    "country": "US"
  },
  "rejectionReason": null,
  "verifiedAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T10:30:00Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

**400** Invalid request data

**401** Invalid or missing API key

---

## Check verification status

`POST /api/v1/api/v1/compliance/verifications/check`

- Auth: X-API-Key header
- Operation ID: `ComplianceController_checkVerification`

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | string | yes | User ID to check verification status |
| `type` | enum ("identity", "document", "address", "phone", "email") | yes | Type of verification to check |

```json
{
  "userId": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "type": "identity"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/api/v1/compliance/verifications/check \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "type": "identity"
}'
```

### Responses

**200** Verification status retrieved

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "platformId": "550e8400-e29b-41d4-a716-446655440001",
  "userId": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "type": "identity",
  "status": "approved",
  "level": "basic",
  "riskRating": "low",
  "provider": "persona",
  "externalInquiryId": "inq_ABC123",
  "externalSessionToken": "session_token_xyz",
  "metadata": {
    "email": "user@example.com",
    "country": "US"
  },
  "rejectionReason": null,
  "verifiedAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T10:30:00Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

**404** Verification not found

---

## Get verification by ID

`GET /api/v1/api/v1/compliance/verifications/{id}`

- Auth: X-API-Key header
- Operation ID: `ComplianceController_getVerification`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/api/v1/compliance/verifications/<id> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Verification found

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "platformId": "550e8400-e29b-41d4-a716-446655440001",
  "userId": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "type": "identity",
  "status": "approved",
  "level": "basic",
  "riskRating": "low",
  "provider": "persona",
  "externalInquiryId": "inq_ABC123",
  "externalSessionToken": "session_token_xyz",
  "metadata": {
    "email": "user@example.com",
    "country": "US"
  },
  "rejectionReason": null,
  "verifiedAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T10:30:00Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

**404** Verification not found

---

## Webhook endpoint for Persona verification updates

`POST /api/v1/api/v1/compliance/webhooks/persona`

- Auth: X-API-Key header
- Operation ID: `ComplianceController_handlePersonaWebhook`

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/api/v1/compliance/webhooks/persona \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Webhook processed successfully


---

# disputes (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/disputes/
> Staging base URL: https://api-staging.coinbax.com

## Get all disputes for platform

`GET /api/v1/disputes`

- Auth: Bearer token
- Operation ID: `DisputeController_getDisputes`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | enum ("open", "under_review", "pending_votes", "in_arbitration", "resolved") | no | Filter by dispute status |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/disputes \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Disputes retrieved successfully

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "transactionId": "550e8400-e29b-41d4-a716-446655440001",
    "initiatedBy": "sender",
    "currentTier": "tier_1_smart_contract",
    "status": "open",
    "reason": "Product not as described",
    "tier1CompletedAt": "2024-01-15T10:30:00Z",
    "tier2CompletedAt": "2024-01-16T10:30:00Z",
    "resolvedAt": "2024-01-17T10:30:00Z",
    "outcome": "favor_sender",
    "resolutionReason": "Evidence clearly shows product defect",
    "refundPercentage": 50,
    "metadata": {},
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "evidence": [
      {
        "id": "string",
        "disputeId": "string",
        "submittedBy": "string",
        "type": "string",
        "title": "string",
        "description": {},
        "content": {},
        "fileUrl": {},
        "fileHash": {},
        "isEncrypted": true,
        "metadata": {},
        "createdAt": "2026-01-15T12:00:00.000Z"
      }
    ]
  }
]
```

---

## Create a new dispute for a transaction

`POST /api/v1/disputes`

- Auth: Bearer token
- Operation ID: `DisputeController_createDispute`

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transactionId` | string | yes | Transaction ID to dispute |
| `initiatedBy` | enum ("sender", "receiver") | yes | Who is initiating the dispute |
| `reason` | string | yes | Reason for the dispute |
| `metadata` | object | no | Additional metadata |

```json
{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "initiatedBy": "sender",
  "reason": "Product not as described",
  "metadata": {
    "category": "product_quality"
  }
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/disputes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "initiatedBy": "sender",
  "reason": "Product not as described",
  "metadata": {
    "category": "product_quality"
  }
}'
```

### Responses

**201** Dispute created successfully

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "transactionId": "550e8400-e29b-41d4-a716-446655440001",
  "initiatedBy": "sender",
  "currentTier": "tier_1_smart_contract",
  "status": "open",
  "reason": "Product not as described",
  "tier1CompletedAt": "2024-01-15T10:30:00Z",
  "tier2CompletedAt": "2024-01-16T10:30:00Z",
  "resolvedAt": "2024-01-17T10:30:00Z",
  "outcome": "favor_sender",
  "resolutionReason": "Evidence clearly shows product defect",
  "refundPercentage": 50,
  "metadata": {},
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "evidence": [
    {
      "id": "string",
      "disputeId": "string",
      "submittedBy": "string",
      "type": "string",
      "title": "string",
      "description": {},
      "content": {},
      "fileUrl": {},
      "fileHash": {},
      "isEncrypted": true,
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

**400** Invalid request data or transaction not disputable

**404** Transaction not found

**409** Dispute already exists for this transaction

---

## Get dispute by ID

`GET /api/v1/disputes/{id}`

- Auth: Bearer token
- Operation ID: `DisputeController_getDispute`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/disputes/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Dispute found

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "transactionId": "550e8400-e29b-41d4-a716-446655440001",
  "initiatedBy": "sender",
  "currentTier": "tier_1_smart_contract",
  "status": "open",
  "reason": "Product not as described",
  "tier1CompletedAt": "2024-01-15T10:30:00Z",
  "tier2CompletedAt": "2024-01-16T10:30:00Z",
  "resolvedAt": "2024-01-17T10:30:00Z",
  "outcome": "favor_sender",
  "resolutionReason": "Evidence clearly shows product defect",
  "refundPercentage": 50,
  "metadata": {},
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "evidence": [
    {
      "id": "string",
      "disputeId": "string",
      "submittedBy": "string",
      "type": "string",
      "title": "string",
      "description": {},
      "content": {},
      "fileUrl": {},
      "fileHash": {},
      "isEncrypted": true,
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

**404** Dispute not found

---

## Escalate dispute to next tier

`POST /api/v1/disputes/{id}/escalate`

- Auth: Bearer token
- Operation ID: `DisputeController_escalateDispute`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/disputes/<id>/escalate \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Dispute escalated successfully

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "transactionId": "550e8400-e29b-41d4-a716-446655440001",
  "initiatedBy": "sender",
  "currentTier": "tier_1_smart_contract",
  "status": "open",
  "reason": "Product not as described",
  "tier1CompletedAt": "2024-01-15T10:30:00Z",
  "tier2CompletedAt": "2024-01-16T10:30:00Z",
  "resolvedAt": "2024-01-17T10:30:00Z",
  "outcome": "favor_sender",
  "resolutionReason": "Evidence clearly shows product defect",
  "refundPercentage": 50,
  "metadata": {},
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "evidence": [
    {
      "id": "string",
      "disputeId": "string",
      "submittedBy": "string",
      "type": "string",
      "title": "string",
      "description": {},
      "content": {},
      "fileUrl": {},
      "fileHash": {},
      "isEncrypted": true,
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

**400** Cannot escalate resolved dispute or already at highest tier

**404** Dispute not found

---

## Submit evidence for a dispute

`POST /api/v1/disputes/{id}/evidence`

- Auth: Bearer token
- Operation ID: `DisputeController_submitEvidence`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `submittedBy` | enum ("sender", "receiver") | yes | Who is submitting the evidence |
| `type` | enum ("text", "image", "document", "screenshot", "communication_log", "other") | yes | Type of evidence |
| `title` | string | yes | Title of the evidence |
| `description` | string | no | Description of the evidence |
| `content` | string | no | Text content (for text evidence) |
| `fileUrl` | string | no | File URL (IPFS or storage) |
| `fileHash` | string | no | Hash of the file for verification |
| `isEncrypted` | boolean | no | Whether the evidence is encrypted |
| `metadata` | object | no | Additional metadata |

```json
{
  "submittedBy": "sender",
  "type": "screenshot",
  "title": "Screenshot of product defect",
  "description": "This shows the damaged packaging upon delivery",
  "content": "Conversation log...",
  "fileUrl": "ipfs://QmXyz123...",
  "fileHash": "0xabc123...",
  "isEncrypted": true,
  "metadata": {
    "fileSize": 1024000,
    "mimeType": "image/png"
  }
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/disputes/<id>/evidence \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "submittedBy": "sender",
  "type": "screenshot",
  "title": "Screenshot of product defect",
  "description": "This shows the damaged packaging upon delivery",
  "content": "Conversation log...",
  "fileUrl": "ipfs://QmXyz123...",
  "fileHash": "0xabc123...",
  "isEncrypted": true,
  "metadata": {
    "fileSize": 1024000,
    "mimeType": "image/png"
  }
}'
```

### Responses

**201** Evidence submitted successfully

```json
{
  "id": "string",
  "disputeId": "string",
  "submittedBy": "string",
  "type": "string",
  "title": "string",
  "description": {},
  "content": {},
  "fileUrl": {},
  "fileHash": {},
  "isEncrypted": true,
  "metadata": {},
  "createdAt": "2026-01-15T12:00:00.000Z"
}
```

**400** Cannot submit evidence to resolved dispute

**404** Dispute not found

---

## Resolve a dispute

`POST /api/v1/disputes/{id}/resolve`

- Auth: Bearer token
- Operation ID: `DisputeController_resolveDispute`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `outcome` | enum ("favor_sender", "favor_receiver", "partial_refund") | yes | Outcome of the dispute |
| `resolutionReason` | string | yes | Reason for the resolution |
| `refundPercentage` | number | no | Refund percentage (0-100) if partial refund |

```json
{
  "outcome": "favor_sender",
  "resolutionReason": "Evidence clearly shows product defect",
  "refundPercentage": 50
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/disputes/<id>/resolve \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "outcome": "favor_sender",
  "resolutionReason": "Evidence clearly shows product defect",
  "refundPercentage": 50
}'
```

### Responses

**200** Dispute resolved successfully

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "transactionId": "550e8400-e29b-41d4-a716-446655440001",
  "initiatedBy": "sender",
  "currentTier": "tier_1_smart_contract",
  "status": "open",
  "reason": "Product not as described",
  "tier1CompletedAt": "2024-01-15T10:30:00Z",
  "tier2CompletedAt": "2024-01-16T10:30:00Z",
  "resolvedAt": "2024-01-17T10:30:00Z",
  "outcome": "favor_sender",
  "resolutionReason": "Evidence clearly shows product defect",
  "refundPercentage": 50,
  "metadata": {},
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "evidence": [
    {
      "id": "string",
      "disputeId": "string",
      "submittedBy": "string",
      "type": "string",
      "title": "string",
      "description": {},
      "content": {},
      "fileUrl": {},
      "fileHash": {},
      "isEncrypted": true,
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

**400** Dispute already resolved or invalid resolution data

**404** Dispute not found


---

# webhooks (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/webhooks/
> Staging base URL: https://api-staging.coinbax.com

## List webhook subscriptions

`GET /api/v1/webhooks`

- Auth: X-API-Key header
- Operation ID: `WebhookController_list`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `isActive` | query | string | yes |  |
| `eventType` | query | string | yes |  |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/webhooks?isActive=<isActive>&eventType=<eventType> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** List of webhook subscriptions

---

## Create webhook subscription

`POST /api/v1/webhooks`

- Auth: X-API-Key header
- Operation ID: `WebhookController_create`

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | The URL to send webhook events to |
| `eventTypes` | array of string | yes | Event types to subscribe to |
| `ipWhitelist` | array of string | no | Optional list of IP addresses allowed to send webhooks |
| `metadata` | object | no | Optional metadata for the subscription |

```json
{
  "url": "https://api.example.com/webhooks",
  "eventTypes": [
    "transaction.created",
    "transaction.completed"
  ],
  "ipWhitelist": [
    "1.2.3.4",
    "5.6.7.8"
  ],
  "metadata": {
    "environment": "production",
    "team": "payments"
  }
}
```

### Example request

```bash
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://api.example.com/webhooks",
  "eventTypes": [
    "transaction.created",
    "transaction.completed"
  ],
  "ipWhitelist": [
    "1.2.3.4",
    "5.6.7.8"
  ],
  "metadata": {
    "environment": "production",
    "team": "payments"
  }
}'
```

### Responses

**201** Webhook subscription created successfully

**400** Invalid event types

**401** Unauthorized

---

## Get available webhook event types

`GET /api/v1/webhooks/events/types`

- Auth: X-API-Key header
- Operation ID: `WebhookController_getEventTypes`

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/webhooks/events/types \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** List of available event types

---

## Get webhook subscription

`GET /api/v1/webhooks/{id}`

- Auth: X-API-Key header
- Operation ID: `WebhookController_get`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/webhooks/<id> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Webhook subscription details

**404** Subscription not found

---

## Delete webhook subscription

`DELETE /api/v1/webhooks/{id}`

- Auth: X-API-Key header
- Operation ID: `WebhookController_delete`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Example request

```bash
curl -X DELETE https://api-staging.coinbax.com/api/v1/webhooks/<id> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Webhook subscription deleted

**404** Subscription not found

---

## Update webhook subscription

`PATCH /api/v1/webhooks/{id}`

- Auth: X-API-Key header
- Operation ID: `WebhookController_update`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | no | The URL to send webhook events to |
| `eventTypes` | array of string | no | Event types to subscribe to |
| `isActive` | boolean | no | Whether the subscription is active |
| `ipWhitelist` | array of string | no | Optional list of IP addresses allowed to send webhooks |
| `metadata` | object | no | Optional metadata for the subscription |

```json
{
  "url": "https://api.example.com/webhooks/v2",
  "eventTypes": [
    "transaction.created",
    "transaction.completed",
    "transaction.refunded"
  ],
  "isActive": true,
  "ipWhitelist": [
    "1.2.3.4",
    "5.6.7.8"
  ],
  "metadata": {
    "environment": "production",
    "team": "payments"
  }
}
```

### Example request

```bash
curl -X PATCH https://api-staging.coinbax.com/api/v1/webhooks/<id> \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://api.example.com/webhooks/v2",
  "eventTypes": [
    "transaction.created",
    "transaction.completed",
    "transaction.refunded"
  ],
  "isActive": true,
  "ipWhitelist": [
    "1.2.3.4",
    "5.6.7.8"
  ],
  "metadata": {
    "environment": "production",
    "team": "payments"
  }
}'
```

### Responses

**200** Webhook subscription updated

**400** Invalid event types

**404** Subscription not found

---

## Complete secret rotation

`POST /api/v1/webhooks/{id}/complete-rotation`

- Auth: X-API-Key header
- Operation ID: `WebhookController_completeRotation`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/webhooks/<id>/complete-rotation \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Secret rotation completed

**400** No rotation in progress

**404** Subscription not found

---

## Get webhook delivery logs

`GET /api/v1/webhooks/{id}/delivery-logs`

- Auth: X-API-Key header
- Operation ID: `WebhookController_deliveryLogs`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |
| `limit` | query | number | no | Number of logs to return |
| `offset` | query | number | no | Number of logs to skip |
| `successOnly` | query | boolean | no | Filter for successful deliveries only |
| `failuresOnly` | query | boolean | no | Filter for failed deliveries only |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/webhooks/<id>/delivery-logs \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Delivery logs with pagination

**404** Subscription not found

---

## Reset circuit breaker

`POST /api/v1/webhooks/{id}/reset-circuit-breaker`

- Auth: X-API-Key header
- Operation ID: `WebhookController_resetCircuitBreaker`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/webhooks/<id>/reset-circuit-breaker \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Circuit breaker reset

**404** Subscription not found

---

## Rotate webhook secret

`POST /api/v1/webhooks/{id}/rotate-secret`

- Auth: X-API-Key header
- Operation ID: `WebhookController_rotateSecret`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/webhooks/<id>/rotate-secret \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Secret rotation initiated

**404** Subscription not found

---

## Test webhook endpoint

`POST /api/v1/webhooks/{id}/test`

- Auth: X-API-Key header
- Operation ID: `WebhookController_test`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/webhooks/<id>/test \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Test result

**404** Subscription not found


---

# Coinbax Core API

> Source: https://developers.coinbax.com/reference/coinbax-core/
> OpenAPI spec: https://developers.coinbax.com/openapi/coinbax-core.json

## Servers

- https://core.coinbax.com/api/v1 (Production server)
- https://core-staging.coinbax.com/api/v1 (Staging server)

## Endpoint groups

### Authentication (14 operations)

- `POST /auth/login` User login (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authlogin)
- `POST /auth/register` Register new user (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authregister)
- `GET /auth/me` Get current user (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authme)
- `POST /auth/refresh` Refresh access token (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authrefresh)
- `POST /auth/logout` Logout user (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authlogout)
- `POST /auth/change-password` Change password (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authchangepassword)
- `POST /auth/request-password-reset` Request password reset (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authrequestpasswordreset)
- `POST /auth/reset-password` Reset password (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authresetpassword)
- `POST /auth/verify-email` Verify email address (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authverifyemail)
- `POST /auth/link-oauth` Link OAuth provider (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authlinkoauth)
- `POST /auth/unlink-oauth` Unlink OAuth provider (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authunlinkoauth)
- `GET /auth/linked-accounts` List linked OAuth accounts (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authlistlinkedaccounts)
- `POST /auth/google/exchange-code` Exchange Google OAuth code (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authgoogleexchangecode)
- `POST /auth/microsoft/exchange-code` Exchange Microsoft OAuth code (https://developers.coinbax.com/reference/coinbax-core/authentication.md#authmicrosoftexchangecode)

### Workspaces (16 operations)

- `GET /workspaces` List all workspaces (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#listworkspaces)
- `POST /workspaces` Create a new workspace (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#createworkspace)
- `GET /workspaces/me` Get current user's workspace (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#getmyworkspace)
- `PUT /workspaces/me` Update current user's workspace (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#updatemyworkspace)
- `GET /workspaces/{id}` Get workspace by ID (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#getworkspace)
- `PUT /workspaces/{id}` Update workspace (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#updateworkspace)
- `DELETE /workspaces/{id}` Delete workspace (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#deleteworkspace)
- `POST /workspaces/{id}/avatar` Upload workspace avatar (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#uploadworkspaceavatar)
- `DELETE /workspaces/{id}/avatar` Delete workspace avatar (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#deleteworkspaceavatar)
- `GET /workspaces/{id}/billing` Get workspace billing (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#getworkspacebilling)
- `GET /workspaces/{id}/platform-mappings` List platform mappings (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#listworkspaceplatformmappings)
- `POST /workspaces/{id}/platform-mappings` Create platform mapping (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#createworkspaceplatformmapping)
- `DELETE /workspaces/{id}/platform-mappings/{mappingId}` Delete platform mapping (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#deleteworkspaceplatformmapping)
- `GET /workspaces/{id}/wallet-settings` Get wallet settings (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#getworkspacewalletsettings)
- `PATCH /workspaces/{id}/wallet-settings` Update wallet settings (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#updateworkspacewalletsettings)
- `GET /workspaces/search` Search workspaces (https://developers.coinbax.com/reference/coinbax-core/workspaces.md#searchworkspaces)

### Workspace Customers (8 operations)

- `GET /workspaces/{id}/customers` List workspace customers (https://developers.coinbax.com/reference/coinbax-core/workspace-customers.md#listworkspacecustomers)
- `POST /workspaces/{id}/customers` Create customer in workspace (https://developers.coinbax.com/reference/coinbax-core/workspace-customers.md#createworkspacecustomer)
- `POST /workspaces/{id}/customers/auth/register` Register customer (https://developers.coinbax.com/reference/coinbax-core/workspace-customers.md#registerworkspacecustomer)
- `POST /workspaces/{id}/customers/auth/login` Login customer (https://developers.coinbax.com/reference/coinbax-core/workspace-customers.md#loginworkspacecustomer)
- `GET /workspaces/{id}/customers/auth/me` Get current customer (https://developers.coinbax.com/reference/coinbax-core/workspace-customers.md#getcurrentworkspacecustomer)
- `POST /workspaces/{id}/customers/auth/refresh` Refresh customer token (https://developers.coinbax.com/reference/coinbax-core/workspace-customers.md#refreshworkspacecustomertoken)
- `POST /workspaces/{id}/customers/auth/link-wallet` Link wallet to customer (https://developers.coinbax.com/reference/coinbax-core/workspace-customers.md#linkworkspacecustomerwallet)
- `GET /workspaces/{id}/customers/auth/wallet` Get customer wallet (https://developers.coinbax.com/reference/coinbax-core/workspace-customers.md#getworkspacecustomerwallet)

### Workspace Transactions (4 operations)

- `GET /workspaces/{id}/transactions` List workspace transactions (https://developers.coinbax.com/reference/coinbax-core/workspace-transactions.md#listworkspacetransactions)
- `POST /workspaces/{id}/transactions` Create transaction in workspace (https://developers.coinbax.com/reference/coinbax-core/workspace-transactions.md#createworkspacetransaction)
- `GET /workspaces/{id}/transactions/{txId}` Get transaction by ID (https://developers.coinbax.com/reference/coinbax-core/workspace-transactions.md#getworkspacetransaction)
- `POST /workspaces/{id}/transactions/{txId}/submit-escrow-hash` Submit escrow transaction hash (https://developers.coinbax.com/reference/coinbax-core/workspace-transactions.md#submitescrowhash)

### Workspace Webhooks (11 operations)

- `GET /workspaces/{id}/webhooks` List webhook subscriptions (https://developers.coinbax.com/reference/coinbax-core/workspace-webhooks.md#listworkspacewebhooks)
- `POST /workspaces/{id}/webhooks` Create webhook subscription (https://developers.coinbax.com/reference/coinbax-core/workspace-webhooks.md#createworkspacewebhook)
- `GET /workspaces/{id}/webhooks/{webhookId}` Get webhook subscription (https://developers.coinbax.com/reference/coinbax-core/workspace-webhooks.md#getworkspacewebhook)
- `DELETE /workspaces/{id}/webhooks/{webhookId}` Delete webhook subscription (https://developers.coinbax.com/reference/coinbax-core/workspace-webhooks.md#deleteworkspacewebhook)
- `PATCH /workspaces/{id}/webhooks/{webhookId}` Update webhook subscription (https://developers.coinbax.com/reference/coinbax-core/workspace-webhooks.md#updateworkspacewebhook)
- `GET /workspaces/{id}/webhooks/{webhookId}/delivery-logs` Get webhook delivery logs (https://developers.coinbax.com/reference/coinbax-core/workspace-webhooks.md#getworkspacewebhookdeliverylogs)
- `POST /workspaces/{id}/webhooks/{webhookId}/rotate-secret` Initiate secret rotation (https://developers.coinbax.com/reference/coinbax-core/workspace-webhooks.md#rotateworkspacewebhooksecret)
- `POST /workspaces/{id}/webhooks/{webhookId}/complete-rotation` Complete secret rotation (https://developers.coinbax.com/reference/coinbax-core/workspace-webhooks.md#completeworkspacewebhookrotation)
- `POST /workspaces/{id}/webhooks/{webhookId}/reset-circuit-breaker` Reset circuit breaker (https://developers.coinbax.com/reference/coinbax-core/workspace-webhooks.md#resetworkspacewebhookcircuitbreaker)
- `POST /workspaces/{id}/webhooks/{webhookId}/test` Test webhook endpoint (https://developers.coinbax.com/reference/coinbax-core/workspace-webhooks.md#testworkspacewebhook)
- `GET /workspaces/{id}/webhooks/events/types` List webhook event types (https://developers.coinbax.com/reference/coinbax-core/workspace-webhooks.md#listworkspacewebhookeventtypes)

### Workspace OAuth (8 operations)

- `GET /workspaces/{id}/oauth/clients` List OAuth clients (https://developers.coinbax.com/reference/coinbax-core/workspace-oauth.md#listworkspaceoauthclients)
- `POST /workspaces/{id}/oauth/clients` Create OAuth client (https://developers.coinbax.com/reference/coinbax-core/workspace-oauth.md#createworkspaceoauthclient)
- `GET /workspaces/{id}/oauth/clients/{clientId}` Get OAuth client (https://developers.coinbax.com/reference/coinbax-core/workspace-oauth.md#getworkspaceoauthclient)
- `DELETE /workspaces/{id}/oauth/clients/{clientId}` Delete OAuth client (https://developers.coinbax.com/reference/coinbax-core/workspace-oauth.md#deleteworkspaceoauthclient)
- `PATCH /workspaces/{id}/oauth/clients/{clientId}` Update OAuth client (https://developers.coinbax.com/reference/coinbax-core/workspace-oauth.md#updateworkspaceoauthclient)
- `POST /workspaces/{id}/oauth/clients/{clientId}/revoke-tokens` Revoke OAuth client tokens (https://developers.coinbax.com/reference/coinbax-core/workspace-oauth.md#revokeworkspaceoauthclienttokens)
- `GET /workspaces/{id}/oauth/clients/{clientId}/stats` Get OAuth client statistics (https://developers.coinbax.com/reference/coinbax-core/workspace-oauth.md#getworkspaceoauthclientstats)
- `GET /workspaces/{id}/oauth/scopes` List available OAuth scopes (https://developers.coinbax.com/reference/coinbax-core/workspace-oauth.md#listworkspaceoauthscopes)

### Customers (9 operations)

- `GET /customers` List all customers (https://developers.coinbax.com/reference/coinbax-core/customers.md#listcustomers)
- `POST /customers` Create a new customer (https://developers.coinbax.com/reference/coinbax-core/customers.md#createcustomer)
- `GET /customers/{id}` Get customer by ID (https://developers.coinbax.com/reference/coinbax-core/customers.md#getcustomer)
- `PUT /customers/{id}` Update customer (https://developers.coinbax.com/reference/coinbax-core/customers.md#updatecustomer)
- `DELETE /customers/{id}` Delete customer (https://developers.coinbax.com/reference/coinbax-core/customers.md#deletecustomer)
- `GET /customers/{id}/circle-wallet` Get customer Circle wallet (https://developers.coinbax.com/reference/coinbax-core/customers.md#getcustomercirclewallet)
- `POST /customers/{id}/circle-wallet` Provision Circle wallet for customer (https://developers.coinbax.com/reference/coinbax-core/customers.md#createcustomercirclewallet)
- `GET /customers/{id}/circle-wallet/balance` Get customer Circle wallet balance (https://developers.coinbax.com/reference/coinbax-core/customers.md#getcustomercirclewalletbalance)
- `GET /customers/{id}/transactions` Get customer transactions (https://developers.coinbax.com/reference/coinbax-core/customers.md#getcustomertransactions)

### Transactions (3 operations)

- `GET /transactions` List transactions (https://developers.coinbax.com/reference/coinbax-core/transactions.md#listtransactions)
- `GET /transactions/{id}` Get transaction by ID (https://developers.coinbax.com/reference/coinbax-core/transactions.md#gettransaction)
- `GET /transactions/stats` Get transaction statistics (https://developers.coinbax.com/reference/coinbax-core/transactions.md#gettransactionstats)

### Users (11 operations)

- `GET /users` List all users (https://developers.coinbax.com/reference/coinbax-core/users.md#listusers)
- `POST /users` Create a new user (https://developers.coinbax.com/reference/coinbax-core/users.md#createuser)
- `GET /users/me` Get current user profile (https://developers.coinbax.com/reference/coinbax-core/users.md#getcurrentuser)
- `PUT /users/me` Update current user profile (https://developers.coinbax.com/reference/coinbax-core/users.md#updatecurrentuser)
- `GET /users/{id}` Get user by ID (https://developers.coinbax.com/reference/coinbax-core/users.md#getuser)
- `PUT /users/{id}` Update user (https://developers.coinbax.com/reference/coinbax-core/users.md#updateuser)
- `DELETE /users/{id}` Delete user (https://developers.coinbax.com/reference/coinbax-core/users.md#deleteuser)
- `POST /users/me/avatar` Upload user avatar (https://developers.coinbax.com/reference/coinbax-core/users.md#uploaduseravatar)
- `DELETE /users/me/avatar` Delete user avatar (https://developers.coinbax.com/reference/coinbax-core/users.md#deleteuseravatar)
- `PATCH /users/me/password` Update password (https://developers.coinbax.com/reference/coinbax-core/users.md#updateuserpassword)
- `GET /users/{id}/audit-logs` Get user audit logs (https://developers.coinbax.com/reference/coinbax-core/users.md#getuserauditlogs)

### Wallet Configs (4 operations)

- `GET /workspaces/{id}/external-wallet-configs` List external wallet configs (https://developers.coinbax.com/reference/coinbax-core/wallet-configs.md#listexternalwalletconfigs)
- `GET /workspaces/{id}/external-wallet-configs/{type}` Get external wallet config (https://developers.coinbax.com/reference/coinbax-core/wallet-configs.md#getexternalwalletconfig)
- `PUT /workspaces/{id}/external-wallet-configs/{type}` Create or update external wallet config (https://developers.coinbax.com/reference/coinbax-core/wallet-configs.md#updateexternalwalletconfig)
- `DELETE /workspaces/{id}/external-wallet-configs/{type}` Delete external wallet config (https://developers.coinbax.com/reference/coinbax-core/wallet-configs.md#deleteexternalwalletconfig)

### Notifications (7 operations)

- `GET /notifications` List notifications (https://developers.coinbax.com/reference/coinbax-core/notifications.md#listnotifications)
- `DELETE /notifications` Delete all notifications (https://developers.coinbax.com/reference/coinbax-core/notifications.md#deleteallnotifications)
- `PATCH /notifications/{id}/read` Mark notification as read (https://developers.coinbax.com/reference/coinbax-core/notifications.md#marknotificationasread)
- `POST /notifications/mark-all-read` Mark all notifications as read (https://developers.coinbax.com/reference/coinbax-core/notifications.md#markallnotificationsasread)
- `GET /notifications/{id}` Get notification (https://developers.coinbax.com/reference/coinbax-core/notifications.md#getnotification)
- `GET /notifications/preferences` Get preferences (https://developers.coinbax.com/reference/coinbax-core/notifications.md#getnotificationpreferences)
- `PATCH /notifications/preferences` Update preferences (https://developers.coinbax.com/reference/coinbax-core/notifications.md#updatenotificationpreferences)

### Settings (6 operations)

- `GET /settings` List global settings (https://developers.coinbax.com/reference/coinbax-core/settings.md#listsettings)
- `POST /settings` Create or update global setting (https://developers.coinbax.com/reference/coinbax-core/settings.md#createsetting)
- `GET /settings/{key}` Get setting (https://developers.coinbax.com/reference/coinbax-core/settings.md#getsettingbykey)
- `PUT /settings/{key}` Update setting (https://developers.coinbax.com/reference/coinbax-core/settings.md#updatesetting)
- `GET /global-settings` List global settings (https://developers.coinbax.com/reference/coinbax-core/settings.md#listglobalsettings)
- `POST /global-settings/bulk` Update settings bulk (https://developers.coinbax.com/reference/coinbax-core/settings.md#updateglobalsettingsbulk)

### Audit Logs (5 operations)

- `GET /workspaces/{id}/audit-logs` List workspace audit logs (https://developers.coinbax.com/reference/coinbax-core/audit-logs.md#listworkspaceauditlogs)
- `GET /audit-logs` List all audit logs (https://developers.coinbax.com/reference/coinbax-core/audit-logs.md#listallauditlogs)
- `GET /audit-logs/{id}` Get audit log entry (https://developers.coinbax.com/reference/coinbax-core/audit-logs.md#getauditlog)
- `GET /audit-logs/export` Export audit logs (https://developers.coinbax.com/reference/coinbax-core/audit-logs.md#exportauditlogs)
- `GET /audit-logs/stats` Get audit log statistics (https://developers.coinbax.com/reference/coinbax-core/audit-logs.md#getauditlogstats)

### Smart Contracts (4 operations)

- `GET /workspaces/{id}/contracts` List contract deployments (https://developers.coinbax.com/reference/coinbax-core/smart-contracts.md#listworkspacecontracts)
- `GET /workspaces/{id}/contracts/{network}` Get escrow contract address for network (https://developers.coinbax.com/reference/coinbax-core/smart-contracts.md#getworkspacecontractbynetwork)
- `POST /workspaces/{id}/contracts/{network}` Deploy dedicated escrow contract (https://developers.coinbax.com/reference/coinbax-core/smart-contracts.md#deployworkspacecontract)
- `POST /workspaces/{id}/contracts/deployments/{deploymentId}/deprecate` Deprecate contract deployment (https://developers.coinbax.com/reference/coinbax-core/smart-contracts.md#deprecatecontractdeployment)

### Integrations (9 operations)

- `GET /workspaces/{id}/integrations` List workspace integrations (https://developers.coinbax.com/reference/coinbax-core/integrations.md#listworkspaceintegrations)
- `POST /workspaces/{id}/integrations` Enable integration (https://developers.coinbax.com/reference/coinbax-core/integrations.md#enableworkspaceintegration)
- `GET /workspaces/{id}/integrations/{integrationId}` Get integration details (https://developers.coinbax.com/reference/coinbax-core/integrations.md#getworkspaceintegration)
- `DELETE /workspaces/{id}/integrations/{integrationId}` Remove integration (https://developers.coinbax.com/reference/coinbax-core/integrations.md#deleteworkspaceintegration)
- `PATCH /workspaces/{id}/integrations/{integrationId}` Update integration (https://developers.coinbax.com/reference/coinbax-core/integrations.md#updateworkspaceintegration)
- `POST /workspaces/{id}/integrations/{integrationId}/disable` Disable integration (https://developers.coinbax.com/reference/coinbax-core/integrations.md#disableworkspaceintegration)
- `GET /workspaces/{id}/integrations/{integrationId}/status` Get integration status (https://developers.coinbax.com/reference/coinbax-core/integrations.md#getworkspaceintegrationstatus)
- `POST /workspaces/{id}/integrations/validate` Validate integration config (https://developers.coinbax.com/reference/coinbax-core/integrations.md#validateworkspaceintegration)
- `POST /workspaces/{id}/integrations/with-config` Enable integration with config (https://developers.coinbax.com/reference/coinbax-core/integrations.md#enableworkspaceintegrationwithconfig)

### Health (4 operations)

- `GET /health` Health check (https://developers.coinbax.com/reference/coinbax-core/health.md#healthcheck)
- `GET /health/database` Database health check (https://developers.coinbax.com/reference/coinbax-core/health.md#healthcheckdatabase)
- `GET /health/redis` Redis health check (https://developers.coinbax.com/reference/coinbax-core/health.md#healthcheckredis)
- `GET /health/storage` Storage health check (https://developers.coinbax.com/reference/coinbax-core/health.md#healthcheckstorage)

### Onboarding (4 operations)

- `GET /onboarding` Get onboarding status (https://developers.coinbax.com/reference/coinbax-core/onboarding.md#getonboardingstatus)
- `POST /onboarding/complete` Complete onboarding (https://developers.coinbax.com/reference/coinbax-core/onboarding.md#completeonboarding)
- `POST /onboarding/skip` Skip onboarding (https://developers.coinbax.com/reference/coinbax-core/onboarding.md#skiponboarding)
- `POST /onboarding/create-client` Create client (https://developers.coinbax.com/reference/coinbax-core/onboarding.md#onboardingcreateclient)

### Workspace Users (2 operations)

- `GET /workspaces/{id}/users` List workspace users (https://developers.coinbax.com/reference/coinbax-core/workspace-users.md#listworkspaceusers)
- `POST /workspaces/me/invite-users` Invite users to workspace (https://developers.coinbax.com/reference/coinbax-core/workspace-users.md#inviteworkspaceusers)

### Workspace Wallets (3 operations)

- `GET /workspaces/{id}/wallet-accounts` List wallet accounts (https://developers.coinbax.com/reference/coinbax-core/workspace-wallets.md#listworkspacewalletaccounts)
- `POST /workspaces/{id}/wallet-accounts` Create wallet accounts (https://developers.coinbax.com/reference/coinbax-core/workspace-wallets.md#createworkspacewalletaccounts)
- `GET /workspaces/{id}/wallet-balances` Get wallet balances (https://developers.coinbax.com/reference/coinbax-core/workspace-wallets.md#getworkspacewalletbalances)

### Wallet Provider Configs (10 operations)

- `GET /wallet-provider-configs` List wallet provider configurations (https://developers.coinbax.com/reference/coinbax-core/wallet-provider-configs.md#listwalletproviderconfigs)
- `POST /wallet-provider-configs` Create wallet provider configuration (https://developers.coinbax.com/reference/coinbax-core/wallet-provider-configs.md#createwalletproviderconfig)
- `GET /wallet-provider-configs/{id}` Get wallet provider configuration (https://developers.coinbax.com/reference/coinbax-core/wallet-provider-configs.md#getwalletproviderconfig)
- `DELETE /wallet-provider-configs/{id}` Delete wallet provider configuration (https://developers.coinbax.com/reference/coinbax-core/wallet-provider-configs.md#deletewalletproviderconfig)
- `PATCH /wallet-provider-configs/{id}` Update wallet provider configuration (https://developers.coinbax.com/reference/coinbax-core/wallet-provider-configs.md#updatewalletproviderconfig)
- `POST /wallet-provider-configs/{id}/test-connection` Test wallet provider connection (https://developers.coinbax.com/reference/coinbax-core/wallet-provider-configs.md#testwalletproviderconnection)
- `GET /wallet-provider-configs/status` Get wallet provider config status (https://developers.coinbax.com/reference/coinbax-core/wallet-provider-configs.md#getwalletproviderconfigstatus)
- `GET /wallet-provider-configs/check-duplicate` Check for duplicate wallet provider config (https://developers.coinbax.com/reference/coinbax-core/wallet-provider-configs.md#checkduplicatewalletproviderconfig)
- `POST /wallet-provider-configs/{id}/set-default` Set wallet provider config as default (https://developers.coinbax.com/reference/coinbax-core/wallet-provider-configs.md#setdefaultwalletproviderconfig)
- `GET /wallet-provider-configs/effective` Get effective wallet provider configuration (https://developers.coinbax.com/reference/coinbax-core/wallet-provider-configs.md#geteffectivewalletproviderconfig)


---

# Authentication (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/authentication/
> Staging base URL: https://core-staging.coinbax.com/api/v1

User authentication and session management

## User login

`POST /auth/login`

- Auth: Public (no authentication)
- Operation ID: `authLogin`

Authenticate a user with email and password. Returns access token and refresh token.

The access token expires in 1 hour, refresh token in 7 days.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes | User's email address |
| `password` | string (password) | yes | User's password (min 8 characters) |

```json
{
  "email": "admin@coinbax.com",
  "password": "admin123"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
  "email": "admin@coinbax.com",
  "password": "admin123"
}'
```

### Responses

**200** Login successful

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "admin@coinbax.com",
      "firstName": "Admin",
      "lastName": "User",
      "role": "ADMIN",
      "workspaceId": "123e4567-e89b-12d3-a456-426614174000"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**400** Bad request - validation error

**401** Invalid credentials

**429** Too many requests - rate limit exceeded

**500** Internal server error

---

## Register new user

`POST /auth/register`

- Auth: Public (no authentication)
- Operation ID: `authRegister`

Register a new user account. A verification email will be sent.

**Note:** Registration may be disabled in some deployments.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes | User's email address |
| `password` | string (password) | yes | User's password (min 8 characters) |
| `firstName` | string | yes | User's first name |
| `lastName` | string | yes | User's last name |
| `workspaceName` | string | no | Workspace name (optional, creates new workspace) |

```json
{
  "email": "newuser@example.com",
  "password": "string",
  "firstName": "John",
  "lastName": "Doe",
  "workspaceName": "Acme Corp"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
  "email": "newuser@example.com",
  "password": "string",
  "firstName": "John",
  "lastName": "Doe",
  "workspaceName": "Acme Corp"
}'
```

### Responses

**201** Registration successful

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "newuser@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "CLIENT",
      "emailVerified": false
    },
    "message": "Verification email sent"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**400** Bad request - validation error

**409** Email already exists

**429** Too many requests - rate limit exceeded

**500** Internal server error

---

## Get current user

`GET /auth/me`

- Auth: Bearer token
- Operation ID: `authMe`

Returns the currently authenticated user's profile information

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/auth/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Current user profile

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@coinbax.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "emailVerified": true,
    "avatarPath": "/uploads/avatars/user-123.png",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Refresh access token

`POST /auth/refresh`

- Auth: Public (no authentication)
- Operation ID: `authRefresh`

Exchange a refresh token for a new access token.

The refresh token is single-use and a new refresh token is returned.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refreshToken` | string | yes | The refresh token from login or previous refresh |

```json
{
  "refreshToken": "string"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "string"
}'
```

### Responses

**200** Token refreshed successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "accessToken": "string",
    "refreshToken": "string",
    "expiresIn": 3600
  }
}
```

**401** Invalid or expired refresh token

**500** Internal server error

---

## Logout user

`POST /auth/logout`

- Auth: Bearer token
- Operation ID: `authLogout`

Invalidate the current session and refresh token.

The access token will remain valid until expiration, but the refresh token
will be immediately invalidated.

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/logout \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Logout successful

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "message": "Logged out successfully"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Change password

`POST /auth/change-password`

- Auth: Bearer token
- Operation ID: `authChangePassword`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/change-password \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Password changed

---

## Request password reset

`POST /auth/request-password-reset`

- Auth: Bearer token
- Operation ID: `authRequestPasswordReset`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/request-password-reset \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Reset email sent

---

## Reset password

`POST /auth/reset-password`

- Auth: Bearer token
- Operation ID: `authResetPassword`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/reset-password \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Password reset

---

## Verify email address

`POST /auth/verify-email`

- Auth: Bearer token
- Operation ID: `authVerifyEmail`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/verify-email \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Email verified

---

## Link OAuth provider

`POST /auth/link-oauth`

- Auth: Bearer token
- Operation ID: `authLinkOAuth`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/link-oauth \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Provider linked

---

## Unlink OAuth provider

`POST /auth/unlink-oauth`

- Auth: Bearer token
- Operation ID: `authUnlinkOAuth`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/unlink-oauth \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Provider unlinked

---

## List linked OAuth accounts

`GET /auth/linked-accounts`

- Auth: Bearer token
- Operation ID: `authListLinkedAccounts`

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/auth/linked-accounts \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Accounts retrieved

---

## Exchange Google OAuth code

`POST /auth/google/exchange-code`

- Auth: Bearer token
- Operation ID: `authGoogleExchangeCode`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/google/exchange-code \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Authentication successful

---

## Exchange Microsoft OAuth code

`POST /auth/microsoft/exchange-code`

- Auth: Bearer token
- Operation ID: `authMicrosoftExchangeCode`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/microsoft/exchange-code \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Authentication successful


---

# Workspaces (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/workspaces/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Workspace (tenant) management

## List all workspaces

`GET /workspaces`

- Auth: Bearer token
- Operation ID: `listWorkspaces`

Retrieve a paginated list of all workspaces.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Page number (1-indexed) |
| `limit` | query | integer | no | Items per page |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Workspaces list retrieved successfully

```json
{
  "success": true,
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "email": "contact@acme.com",
      "status": "active",
      "walletProvider": "TURNKEY",
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-02-20T14:30:00.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 50,
      "totalPages": 3
    }
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Create a new workspace

`POST /workspaces`

- Auth: Bearer token
- Operation ID: `createWorkspace`

Create a new workspace (tenant) in the system.

**Permissions:** ADMIN or SUPER_ADMIN only

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Workspace display name |
| `slug` | string | no | URL-friendly identifier (auto-generated if not provided) |
| `email` | string (email) | yes | Workspace contact email |
| `status` | enum ("active", "inactive", "suspended", "pending") | no | Initial workspace status |
| `webhookUrl` | string (uri) | no | Webhook URL for transaction events |
| `walletProvider` | enum ("COINBAX", "CIRCLE", "FIREBLOCKS", "TURNKEY", "UTILA") | no | Wallet provider to use |
| `metadata` | object | no | Custom metadata |

```json
{
  "name": "Acme Corp",
  "email": "contact@acme.com",
  "walletProvider": "TURNKEY",
  "metadata": {
    "industry": "fintech"
  }
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Corp",
  "email": "contact@acme.com",
  "walletProvider": "TURNKEY",
  "metadata": {
    "industry": "fintech"
  }
}'
```

### Responses

**201** Workspace created successfully

```json
{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "email": "contact@acme.com",
    "status": "pending",
    "walletProvider": "TURNKEY",
    "metadata": {
      "industry": "fintech"
    },
    "createdAt": "2026-02-24T12:00:00.000Z",
    "updatedAt": "2026-02-24T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**409** Workspace with this slug already exists

**500** Internal server error

---

## Get current user's workspace

`GET /workspaces/me`

- Auth: Bearer token
- Operation ID: `getMyWorkspace`

Retrieve the workspace associated with the currently authenticated user.

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Workspace retrieved successfully

```json
{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "email": "contact@acme.com",
    "status": "active",
    "walletProvider": "TURNKEY",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**400** User has no associated workspace

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Update current user's workspace

`PUT /workspaces/me`

- Auth: Bearer token
- Operation ID: `updateMyWorkspace`

Update the workspace associated with the currently authenticated user.

Allows workspace members to update their own organization details.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Workspace display name |
| `email` | string (email) | no | Workspace contact email |
| `status` | enum ("active", "inactive", "suspended", "pending") | no | Workspace status |
| `avatarPath` | string | no | Path to workspace avatar image |
| `webhookUrl` | string (uri) | no | Webhook URL for transaction events |
| `walletProvider` | enum ("COINBAX", "CIRCLE", "FIREBLOCKS", "TURNKEY", "UTILA") | no | Wallet provider to use |
| `metadata` | object | no | Custom metadata |

```json
{
  "name": "Acme Corporation",
  "email": "admin@acme.com",
  "webhookUrl": "https://acme.com/webhooks/coinbax-v2"
}
```

### Example request

```bash
curl -X PUT https://core-staging.coinbax.com/api/v1/workspaces/me \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Corporation",
  "email": "admin@acme.com",
  "webhookUrl": "https://acme.com/webhooks/coinbax-v2"
}'
```

### Responses

**200** Workspace updated successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "email": "contact@acme.com",
    "status": "active",
    "avatarPath": "/uploads/avatars/workspace-123.png",
    "webhookUrl": "https://acme.com/webhooks/coinbax",
    "walletProvider": "TURNKEY",
    "walletId": "wallet_abc123",
    "turnkeyOrganizationId": "org_turnkey_xyz",
    "metadata": {
      "industry": "fintech",
      "tier": "enterprise"
    },
    "billingEnabled": false,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Get workspace by ID

`GET /workspaces/{id}`

- Auth: Bearer token
- Operation ID: `getWorkspace`

Retrieve a workspace by its unique identifier.

**Permissions:**
- User must be a member of the workspace OR
- User must be ADMIN or SUPER_ADMIN

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace UUID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Workspace found

```json
{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "email": "contact@acme.com",
    "status": "active",
    "walletProvider": "TURNKEY",
    "webhookUrl": "https://acme.com/webhooks/coinbax",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Access denied - not a member of this workspace

**404** Resource not found

**500** Internal server error

---

## Update workspace

`PUT /workspaces/{id}`

- Auth: Bearer token
- Operation ID: `updateWorkspace`

Update workspace details.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Workspace display name |
| `email` | string (email) | no | Workspace contact email |
| `status` | enum ("active", "inactive", "suspended", "pending") | no | Workspace status |
| `avatarPath` | string | no | Path to workspace avatar image |
| `webhookUrl` | string (uri) | no | Webhook URL for transaction events |
| `walletProvider` | enum ("COINBAX", "CIRCLE", "FIREBLOCKS", "TURNKEY", "UTILA") | no | Wallet provider to use |
| `metadata` | object | no | Custom metadata |

```json
{
  "name": "Acme Corporation",
  "email": "admin@acme.com",
  "webhookUrl": "https://acme.com/webhooks/coinbax-v2"
}
```

### Example request

```bash
curl -X PUT https://core-staging.coinbax.com/api/v1/workspaces/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Corporation",
  "email": "admin@acme.com",
  "webhookUrl": "https://acme.com/webhooks/coinbax-v2"
}'
```

### Responses

**200** Workspace updated successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "email": "contact@acme.com",
    "status": "active",
    "avatarPath": "/uploads/avatars/workspace-123.png",
    "webhookUrl": "https://acme.com/webhooks/coinbax",
    "walletProvider": "TURNKEY",
    "walletId": "wallet_abc123",
    "turnkeyOrganizationId": "org_turnkey_xyz",
    "metadata": {
      "industry": "fintech",
      "tier": "enterprise"
    },
    "billingEnabled": false,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Delete workspace

`DELETE /workspaces/{id}`

- Auth: Bearer token
- Operation ID: `deleteWorkspace`

Permanently delete a workspace.

**Permissions:** ADMIN or SUPER_ADMIN only

**Warning:** This action is irreversible and will delete all associated data.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/workspaces/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**204** Workspace deleted successfully (no content)

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Upload workspace avatar

`POST /workspaces/{id}/avatar`

- Auth: Bearer token
- Operation ID: `uploadWorkspaceAvatar`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/avatar \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Uploaded

---

## Delete workspace avatar

`DELETE /workspaces/{id}/avatar`

- Auth: Bearer token
- Operation ID: `deleteWorkspaceAvatar`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/workspaces/<id>/avatar \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**204** Deleted

---

## Get workspace billing

`GET /workspaces/{id}/billing`

- Auth: Bearer token
- Operation ID: `getWorkspaceBilling`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/billing \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Retrieved

---

## List platform mappings

`GET /workspaces/{id}/platform-mappings`

- Auth: Bearer token
- Operation ID: `listWorkspacePlatformMappings`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/platform-mappings \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Retrieved

---

## Create platform mapping

`POST /workspaces/{id}/platform-mappings`

- Auth: Bearer token
- Operation ID: `createWorkspacePlatformMapping`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/platform-mappings \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**201** Created

---

## Delete platform mapping

`DELETE /workspaces/{id}/platform-mappings/{mappingId}`

- Auth: Bearer token
- Operation ID: `deleteWorkspacePlatformMapping`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |
| `mappingId` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/workspaces/<id>/platform-mappings/<mappingId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**204** Deleted

---

## Get wallet settings

`GET /workspaces/{id}/wallet-settings`

- Auth: Bearer token
- Operation ID: `getWorkspaceWalletSettings`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/wallet-settings \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Retrieved

---

## Update wallet settings

`PATCH /workspaces/{id}/wallet-settings`

- Auth: Bearer token
- Operation ID: `updateWorkspaceWalletSettings`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X PATCH https://core-staging.coinbax.com/api/v1/workspaces/<id>/wallet-settings \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Updated

---

## Search workspaces

`GET /workspaces/search`

- Auth: Bearer token
- Operation ID: `searchWorkspaces`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/search?q=<q> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Results


---

# Workspace Customers (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/workspace-customers/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Customer management within workspaces

## List workspace customers

`GET /workspaces/{id}/customers`

- Auth: Bearer token
- Operation ID: `listWorkspaceCustomers`

Retrieve a paginated list of customers belonging to a specific workspace.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace UUID |
| `page` | query | integer | no | Page number (1-indexed) |
| `limit` | query | integer | no | Items per page |
| `status` | query | enum ("active", "inactive", "suspended", "pending") | no | Filter by customer status |
| `search` | query | string | no | Search by name or email |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Customers list retrieved successfully

```json
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "createdAt": "2026-01-20T08:30:00.000Z",
      "updatedAt": "2026-02-15T16:45:00.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Create customer in workspace

`POST /workspaces/{id}/customers`

- Auth: Bearer token
- Operation ID: `createWorkspaceCustomer`

Create a new customer within a specific workspace.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace UUID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `firstName` | string | yes |  |
| `lastName` | string | yes |  |
| `phoneNumber` | string | no |  |
| `address` | string | no |  |
| `city` | string | no |  |
| `state` | string | no |  |
| `postalCode` | string | no |  |
| `country` | string | no |  |
| `metadata` | object | no |  |

```json
{
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1-555-123-4567",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94102",
  "country": "USA",
  "metadata": {}
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1-555-123-4567",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94102",
  "country": "USA",
  "metadata": {}
}'
```

### Responses

**201** Customer created successfully

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "status": "active",
    "createdAt": "2026-02-24T12:00:00.000Z",
    "updatedAt": "2026-02-24T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Register customer

`POST /workspaces/{id}/customers/auth/register`

- Auth: Public (no authentication)
- Operation ID: `registerWorkspaceCustomer`

Register a new customer for a workspace.

**Authentication:** Public endpoint (no auth required)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Workspace ID or slug |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `password` | string | yes |  |
| `firstName` | string | no |  |
| `lastName` | string | no |  |

```json
{
  "email": "customer@example.com",
  "password": "securePassword123",
  "firstName": "John",
  "lastName": "Doe"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers/auth/register \
  -H "Content-Type: application/json" \
  -d '{
  "email": "customer@example.com",
  "password": "securePassword123",
  "firstName": "John",
  "lastName": "Doe"
}'
```

### Responses

**201** Customer registered successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "customer": {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "email": "developer@example.com",
      "firstName": "string",
      "lastName": "string",
      "walletAddress": "string",
      "status": "pending"
    },
    "accessToken": "string",
    "refreshToken": "string",
    "expiresIn": 100
  }
}
```

**400** Bad request - validation error

**409** Conflict - resource already exists or state conflict

**500** Internal server error

---

## Login customer

`POST /workspaces/{id}/customers/auth/login`

- Auth: Public (no authentication)
- Operation ID: `loginWorkspaceCustomer`

Authenticate a customer and receive access tokens.

**Authentication:** Public endpoint (no auth required)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Workspace ID or slug |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `password` | string | yes |  |

```json
{
  "email": "customer@example.com",
  "password": "securePassword123"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers/auth/login \
  -H "Content-Type: application/json" \
  -d '{
  "email": "customer@example.com",
  "password": "securePassword123"
}'
```

### Responses

**200** Customer logged in successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "customer": {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "email": "developer@example.com",
      "firstName": "string",
      "lastName": "string",
      "walletAddress": "string",
      "status": "pending"
    },
    "accessToken": "string",
    "refreshToken": "string",
    "expiresIn": 100
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Get current customer

`GET /workspaces/{id}/customers/auth/me`

- Auth: Bearer token
- Operation ID: `getCurrentWorkspaceCustomer`

Get the current authenticated customer's profile.

**Requires:** Customer authentication (workspace-specific JWT)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Workspace ID or slug |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers/auth/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Customer profile retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "email": "developer@example.com",
    "firstName": "string",
    "lastName": "string",
    "walletAddress": "string",
    "walletLinkedAt": "2026-01-15T12:00:00.000Z",
    "emailVerified": true,
    "status": "pending"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Refresh customer token

`POST /workspaces/{id}/customers/auth/refresh`

- Auth: Public (no authentication)
- Operation ID: `refreshWorkspaceCustomerToken`

Refresh an expired access token using a refresh token.

**Authentication:** Public endpoint (no auth required)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Workspace ID or slug |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refreshToken` | string | yes |  |

```json
{
  "refreshToken": "string"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "string"
}'
```

### Responses

**200** Token refreshed successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "customer": {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "email": "developer@example.com",
      "firstName": "string",
      "lastName": "string",
      "walletAddress": "string",
      "status": "pending"
    },
    "accessToken": "string",
    "refreshToken": "string",
    "expiresIn": 100
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Link wallet to customer

`POST /workspaces/{id}/customers/auth/link-wallet`

- Auth: Bearer token
- Operation ID: `linkWorkspaceCustomerWallet`

Link an external wallet address to the customer account.
Requires signature verification to prove wallet ownership.

**Requires:** Customer authentication (workspace-specific JWT)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Workspace ID or slug |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `walletAddress` | string | yes | Ethereum wallet address |
| `signature` | string | yes | Signed message proving wallet ownership |
| `message` | string | yes | Original message that was signed |

```json
{
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "signature": "0x...",
  "message": "Link wallet to Coinbax: 1234567890"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers/auth/link-wallet \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "signature": "0x...",
  "message": "Link wallet to Coinbax: 1234567890"
}'
```

### Responses

**200** Wallet linked successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "email": "developer@example.com",
    "firstName": "string",
    "lastName": "string",
    "walletAddress": "string",
    "walletLinkedAt": "2026-01-15T12:00:00.000Z",
    "emailVerified": true,
    "status": "pending"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Get customer wallet

`GET /workspaces/{id}/customers/auth/wallet`

- Auth: Bearer token
- Operation ID: `getWorkspaceCustomerWallet`

Get the linked wallet address for the current customer.

**Requires:** Customer authentication (workspace-specific JWT)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Workspace ID or slug |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers/auth/wallet \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Wallet information retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "walletAddress": "string",
    "walletLinkedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error


---

# Workspace Transactions (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/workspace-transactions/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Transaction management within workspaces

## List workspace transactions

`GET /workspaces/{id}/transactions`

- Auth: Bearer token
- Operation ID: `listWorkspaceTransactions`

Retrieve transactions for a specific workspace. Transactions are aggregated from:
1. Platform mappings (external wallet platforms like Transmitter)
2. Turnkey wallet addresses (for admin-managed wallets)
3. Metadata wallet addresses (fallback)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace UUID |
| `page` | query | integer | no | Page number (1-indexed) |
| `limit` | query | integer | no | Items per page |
| `status` | query | enum ("PENDING", "ESCROWED", "IN_REVIEW", "COMPLETED", "FAILED", "CANCELLED") | no | Filter by transaction status |
| `dateFrom` | query | string (date-time) | no | Start date filter (ISO 8601) |
| `dateTo` | query | string (date-time) | no | End date filter (ISO 8601) |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/transactions \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Transactions list retrieved successfully

```json
{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "tx_550e8400-e29b-41d4-a716-446655440000",
        "status": "COMPLETED",
        "amount": "100.00",
        "currency": "USDC",
        "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
        "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
        "blockchainNetwork": "base",
        "createdAt": "2026-02-24T10:00:00.000Z",
        "_platformName": "Main Platform"
      }
    ],
    "pagination": {
      "total": 150,
      "page": 1,
      "limit": 100,
      "totalPages": 2
    }
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Create transaction in workspace

`POST /workspaces/{id}/transactions`

- Auth: Bearer token
- Operation ID: `createWorkspaceTransaction`

Create a new blockchain transaction for a workspace.

The transaction is proxied to coinbax-api which handles actual blockchain execution.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace UUID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fromAddress` | string | yes | Sender's blockchain address |
| `toAddress` | string | yes | Receiver's blockchain address |
| `amount` | string | yes | Transaction amount |
| `network` | string | yes | Blockchain network (devnet, mainnet-beta, base, ethereum, etc.) |
| `currency` | string | no | Currency to transfer (default USDC) |
| `customerId` | string (uuid) | no | Associated customer ID |
| `orchestrationType` | enum ("raw", "coinbax") | no | Transaction orchestration type (default raw) |
| `templateId` | string (uuid) | no | Control template ID from coinbax-library |
| `controlConfigs` | array of object | no | Override configurations for template controls |
| `metadata` | object | no | Additional transaction metadata |

```json
{
  "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
  "amount": "100.00",
  "network": "base",
  "currency": "USDC",
  "orchestrationType": "raw",
  "metadata": {
    "note": "Payment for services"
  }
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/transactions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
  "amount": "100.00",
  "network": "base",
  "currency": "USDC",
  "orchestrationType": "raw",
  "metadata": {
    "note": "Payment for services"
  }
}'
```

### Responses

**200** Transaction created successfully

```json
{
  "success": true,
  "data": {
    "transaction": {
      "id": "tx_550e8400-e29b-41d4-a716-446655440000",
      "status": "PENDING",
      "amount": "100.00",
      "currency": "USDC",
      "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
      "blockchainNetwork": "base",
      "orchestrationType": "raw",
      "createdAt": "2026-02-24T12:00:00.000Z"
    }
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get transaction by ID

`GET /workspaces/{id}/transactions/{txId}`

- Auth: X-API-Key header
- Operation ID: `getWorkspaceTransaction`

Fetch a single transaction by ID from coinbax-api.
Proxies the request to coinbax-api using the platform's API key.

**Authentication:** X-API-Key header with workspace API key

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace UUID |
| `txId` | path | string (uuid) | yes | Transaction UUID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/transactions/<txId> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Transaction retrieved successfully

```json
{
  "id": "tx_550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "amount": "100.00",
  "currency": "USDC",
  "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
  "blockchainNetwork": "base",
  "chainId": 8453,
  "txHash": "0xabcd...ef12",
  "orchestrationType": "raw",
  "metadata": {
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "customerId": "cust_12345"
  },
  "createdAt": "2026-02-24T10:00:00.000Z",
  "updatedAt": "2026-02-24T10:05:00.000Z",
  "_platformName": "Main Platform",
  "_platformId": "platform_xyz"
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Submit escrow transaction hash

`POST /workspaces/{id}/transactions/{txId}/submit-escrow-hash`

- Auth: X-API-Key header
- Operation ID: `submitEscrowHash`

Submit the escrow deposit transaction hash for a pending transaction.
This confirms that funds have been deposited into the escrow contract.

**Authentication:** X-API-Key header with workspace API key

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace UUID |
| `txId` | path | string (uuid) | yes | Transaction UUID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transactionHash` | string | yes | The blockchain transaction hash of the escrow deposit |

```json
{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/transactions/<txId>/submit-escrow-hash \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}'
```

### Responses

**200** Escrow hash submitted successfully

```json
{
  "success": true,
  "message": "Escrow transaction hash submitted successfully",
  "transaction": {
    "id": "tx_550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "amount": "100.00",
    "currency": "USDC",
    "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "blockchainNetwork": "base",
    "chainId": 8453,
    "txHash": "0xabcd...ef12",
    "orchestrationType": "raw",
    "metadata": {
      "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
      "customerId": "cust_12345"
    },
    "createdAt": "2026-02-24T10:00:00.000Z",
    "updatedAt": "2026-02-24T10:05:00.000Z",
    "_platformName": "Main Platform",
    "_platformId": "platform_xyz"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error


---

# Workspace Webhooks (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/workspace-webhooks/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Webhook management for workspaces

## List webhook subscriptions

`GET /workspaces/{id}/webhooks`

- Auth: Bearer token
- Operation ID: `listWorkspaceWebhooks`

Get all webhook subscriptions for a workspace.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `isActive` | query | boolean | no | Filter by active status |
| `eventType` | query | string | no | Filter by event type |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Webhook subscriptions retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": [
    {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "url": "https://example.com/webhooks/coinbax",
      "eventTypes": [
        "transaction.created",
        "transaction.completed",
        "transaction.failed"
      ],
      "secret": "string",
      "isActive": true,
      "ipWhitelist": [
        "192.168.1.1",
        "10.0.0.0/8"
      ],
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Create webhook subscription

`POST /workspaces/{id}/webhooks`

- Auth: Bearer token
- Operation ID: `createWorkspaceWebhook`

Create a new webhook subscription for a workspace.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string (uri) | yes | Webhook endpoint URL |
| `eventTypes` | array of string | yes | Event types to subscribe to |
| `ipWhitelist` | array of string | no | IP addresses allowed to receive webhooks |
| `metadata` | object | no |  |

```json
{
  "url": "https://example.com/webhooks/coinbax",
  "eventTypes": [
    "transaction.created",
    "transaction.completed"
  ],
  "ipWhitelist": [
    "192.168.1.1"
  ]
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/coinbax",
  "eventTypes": [
    "transaction.created",
    "transaction.completed"
  ],
  "ipWhitelist": [
    "192.168.1.1"
  ]
}'
```

### Responses

**201** Webhook subscription created successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "url": "https://example.com/webhooks/coinbax",
    "eventTypes": [
      "transaction.created",
      "transaction.completed",
      "transaction.failed"
    ],
    "secret": "string",
    "isActive": true,
    "ipWhitelist": [
      "192.168.1.1",
      "10.0.0.0/8"
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get webhook subscription

`GET /workspaces/{id}/webhooks/{webhookId}`

- Auth: Bearer token
- Operation ID: `getWorkspaceWebhook`

Get details of a specific webhook subscription.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Webhook subscription retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "url": "https://example.com/webhooks/coinbax",
    "eventTypes": [
      "transaction.created",
      "transaction.completed",
      "transaction.failed"
    ],
    "secret": "string",
    "isActive": true,
    "ipWhitelist": [
      "192.168.1.1",
      "10.0.0.0/8"
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Delete webhook subscription

`DELETE /workspaces/{id}/webhooks/{webhookId}`

- Auth: Bearer token
- Operation ID: `deleteWorkspaceWebhook`

Delete a webhook subscription.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Webhook subscription deleted successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "message": "Subscription deleted"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Update webhook subscription

`PATCH /workspaces/{id}/webhooks/{webhookId}`

- Auth: Bearer token
- Operation ID: `updateWorkspaceWebhook`

Update a webhook subscription.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string (uri) | no |  |
| `eventTypes` | array of string | no |  |
| `isActive` | boolean | no |  |
| `ipWhitelist` | array of string | no |  |
| `metadata` | object | no |  |

```json
{
  "url": "https://example.com",
  "eventTypes": [
    "string"
  ],
  "isActive": true,
  "ipWhitelist": [
    "string"
  ],
  "metadata": {}
}
```

### Example request

```bash
curl -X PATCH https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com",
  "eventTypes": [
    "string"
  ],
  "isActive": true,
  "ipWhitelist": [
    "string"
  ],
  "metadata": {}
}'
```

### Responses

**200** Webhook subscription updated successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "url": "https://example.com/webhooks/coinbax",
    "eventTypes": [
      "transaction.created",
      "transaction.completed",
      "transaction.failed"
    ],
    "secret": "string",
    "isActive": true,
    "ipWhitelist": [
      "192.168.1.1",
      "10.0.0.0/8"
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get webhook delivery logs

`GET /workspaces/{id}/webhooks/{webhookId}/delivery-logs`

- Auth: Bearer token
- Operation ID: `getWorkspaceWebhookDeliveryLogs`

Get delivery logs for a webhook subscription.

**Requires:** Workspace access

Logs are retained for 30 days. Useful for debugging delivery issues.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |
| `limit` | query | integer | no | Number of logs to return (default 20) |
| `offset` | query | integer | no | Offset for pagination |
| `successOnly` | query | boolean | no | Only return successful deliveries |
| `failuresOnly` | query | boolean | no | Only return failed deliveries |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId>/delivery-logs \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Delivery logs retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "logs": [
      {
        "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "webhookSubscriptionId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "eventType": "transaction.created",
        "eventId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "deliveryAttempt": 1,
        "success": true,
        "statusCode": 200,
        "responseTime": 150,
        "errorMessage": "string",
        "requestHeaders": {},
        "responseBody": "string",
        "createdAt": "2026-01-15T12:00:00.000Z"
      }
    ],
    "total": 150
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Initiate secret rotation

`POST /workspaces/{id}/webhooks/{webhookId}/rotate-secret`

- Auth: Bearer token
- Operation ID: `rotateWorkspaceWebhookSecret`

Start the secret rotation process for a webhook.

**Requires:** Workspace access

**Zero-Downtime Rotation:**
1. Call this endpoint to get a new secret
2. Update your webhook handler to accept both old and new secrets
3. Call `/complete-rotation` to finalize

The old secret remains valid until rotation is completed.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId>/rotate-secret \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Secret rotation initiated

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "newSecret": "whsec_newABC123...",
    "rotationExpiresAt": "2026-02-27T12:00:00Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Complete secret rotation

`POST /workspaces/{id}/webhooks/{webhookId}/complete-rotation`

- Auth: Bearer token
- Operation ID: `completeWorkspaceWebhookRotation`

Complete the secret rotation process.

**Requires:** Workspace access

After calling this, only the new secret will be valid.
Make sure your webhook handler has been updated first.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId>/complete-rotation \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Secret rotation completed

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "message": "Secret rotation completed successfully"
  }
}
```

**400** No active rotation in progress

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Reset circuit breaker

`POST /workspaces/{id}/webhooks/{webhookId}/reset-circuit-breaker`

- Auth: Bearer token
- Operation ID: `resetWorkspaceWebhookCircuitBreaker`

Reset the circuit breaker for a webhook subscription.

**Requires:** Workspace access

**Circuit Breaker States:**
- **CLOSED:** Normal operation
- **OPEN:** Delivery paused (too many failures)
- **HALF_OPEN:** Testing recovery

Use this to manually reset after fixing endpoint issues.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId>/reset-circuit-breaker \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Circuit breaker reset successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "circuitBreakerState": "CLOSED",
    "message": "Circuit breaker reset to CLOSED"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Test webhook endpoint

`POST /workspaces/{id}/webhooks/{webhookId}/test`

- Auth: Bearer token
- Operation ID: `testWorkspaceWebhook`

Send a test event to the webhook endpoint.

**Requires:** Workspace access

Useful for verifying your endpoint is correctly configured
and can receive events.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId>/test \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Test event sent

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "success": true,
    "statusCode": 200,
    "responseTime": 150,
    "error": "string"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## List webhook event types

`GET /workspaces/{id}/webhooks/events/types`

- Auth: Bearer token
- Operation ID: `listWorkspaceWebhookEventTypes`

Get all available webhook event types that can be subscribed to.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/events/types \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Event types retrieved successfully

```json
{
  "success": true,
  "data": {
    "eventTypes": [
      {
        "type": "transaction.created",
        "description": "A new transaction was created",
        "category": "transactions"
      },
      {
        "type": "transaction.completed",
        "description": "A transaction was completed",
        "category": "transactions"
      },
      {
        "type": "dispute.created",
        "description": "A dispute was opened",
        "category": "disputes"
      }
    ]
  },
  "meta": {
    "timestamp": "2026-02-26T12:00:00Z",
    "requestId": "req_abc123"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error


---

# Workspace OAuth (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/workspace-oauth/
> Staging base URL: https://core-staging.coinbax.com/api/v1

OAuth client management for workspaces

## List OAuth clients

`GET /workspaces/{id}/oauth/clients`

- Auth: Bearer token
- Operation ID: `listWorkspaceOAuthClients`

Get all OAuth clients for a workspace.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/oauth/clients \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** OAuth clients retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "clients": [
      {
        "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "clientId": "string",
        "clientSecret": "string",
        "name": "string",
        "description": "string",
        "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "scopes": [
          "transactions:read",
          "customers:write"
        ],
        "grantTypes": [
          "authorization_code"
        ],
        "redirectUris": [
          "https://example.com"
        ],
        "isActive": true,
        "createdAt": "2026-01-15T12:00:00.000Z",
        "updatedAt": "2026-01-15T12:00:00.000Z"
      }
    ]
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Create OAuth client

`POST /workspaces/{id}/oauth/clients`

- Auth: Bearer token
- Operation ID: `createWorkspaceOAuthClient`

Create a new OAuth client for a workspace.

**Requires:** Workspace access

**Note:** The client secret is only returned once at creation time.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Display name for the OAuth client |
| `description` | string | no |  |
| `scopes` | array of string | yes | API scopes this client can access |
| `grantTypes` | array of enum ("authorization_code", "client_credentials", "refresh_token") | no |  |
| `redirectUris` | array of string (uri) | no |  |

```json
{
  "name": "My API Client",
  "description": "Client for mobile app",
  "scopes": [
    "transactions:read",
    "customers:write"
  ],
  "grantTypes": [
    "client_credentials"
  ]
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/oauth/clients \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My API Client",
  "description": "Client for mobile app",
  "scopes": [
    "transactions:read",
    "customers:write"
  ],
  "grantTypes": [
    "client_credentials"
  ]
}'
```

### Responses

**201** OAuth client created successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "clientId": "string",
    "clientSecret": "string",
    "name": "string",
    "description": "string",
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "scopes": [
      "transactions:read",
      "customers:write"
    ],
    "grantTypes": [
      "authorization_code"
    ],
    "redirectUris": [
      "https://example.com"
    ],
    "isActive": true,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get OAuth client

`GET /workspaces/{id}/oauth/clients/{clientId}`

- Auth: Bearer token
- Operation ID: `getWorkspaceOAuthClient`

Get details of a specific OAuth client.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `clientId` | path | string | yes | OAuth client ID (e.g., coinbax_client_xxx) |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/oauth/clients/<clientId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** OAuth client retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "clientId": "string",
    "clientSecret": "string",
    "name": "string",
    "description": "string",
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "scopes": [
      "transactions:read",
      "customers:write"
    ],
    "grantTypes": [
      "authorization_code"
    ],
    "redirectUris": [
      "https://example.com"
    ],
    "isActive": true,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Delete OAuth client

`DELETE /workspaces/{id}/oauth/clients/{clientId}`

- Auth: Bearer token
- Operation ID: `deleteWorkspaceOAuthClient`

Permanently delete an OAuth client.

**Requires:** Workspace access

**Warning:** This action is irreversible and will revoke all associated tokens.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `clientId` | path | string | yes | OAuth client ID |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/workspaces/<id>/oauth/clients/<clientId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**204** OAuth client deleted successfully (no content)

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Update OAuth client

`PATCH /workspaces/{id}/oauth/clients/{clientId}`

- Auth: Bearer token
- Operation ID: `updateWorkspaceOAuthClient`

Update an OAuth client's settings.

**Requires:** Workspace access

**Note:** Deactivating a client will revoke all its tokens.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `clientId` | path | string | yes | OAuth client ID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Display name for the OAuth client |
| `description` | string | no | Description of the client's purpose |
| `scopes` | array of string | no | API scopes this client can access |
| `isActive` | boolean | no | Whether the client is active (deactivating revokes all tokens) |

```json
{
  "name": "Updated Client Name",
  "description": "Updated description",
  "scopes": [
    "transactions:read",
    "customers:read"
  ],
  "isActive": true
}
```

### Example request

```bash
curl -X PATCH https://core-staging.coinbax.com/api/v1/workspaces/<id>/oauth/clients/<clientId> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Updated Client Name",
  "description": "Updated description",
  "scopes": [
    "transactions:read",
    "customers:read"
  ],
  "isActive": true
}'
```

### Responses

**200** OAuth client updated successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "clientId": "string",
    "clientSecret": "string",
    "name": "string",
    "description": "string",
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "scopes": [
      "transactions:read",
      "customers:write"
    ],
    "grantTypes": [
      "authorization_code"
    ],
    "redirectUris": [
      "https://example.com"
    ],
    "isActive": true,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Revoke OAuth client tokens

`POST /workspaces/{id}/oauth/clients/{clientId}/revoke-tokens`

- Auth: Bearer token
- Operation ID: `revokeWorkspaceOAuthClientTokens`

Revoke all active access tokens for an OAuth client.

**Requires:** Workspace access

Use this when you need to immediately invalidate all tokens without
deleting the client itself.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `clientId` | path | string | yes | OAuth client ID |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/oauth/clients/<clientId>/revoke-tokens \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Tokens revoked successfully

```json
{
  "success": true,
  "data": {
    "count": 5
  },
  "meta": {
    "timestamp": "2026-02-26T12:00:00Z",
    "requestId": "req_abc123"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get OAuth client statistics

`GET /workspaces/{id}/oauth/clients/{clientId}/stats`

- Auth: Bearer token
- Operation ID: `getWorkspaceOAuthClientStats`

Get token usage statistics for an OAuth client.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `clientId` | path | string | yes | OAuth client ID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/oauth/clients/<clientId>/stats \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Statistics retrieved successfully

```json
{
  "success": true,
  "data": {
    "totalTokens": 150,
    "activeTokens": 12,
    "revokedTokens": 138
  },
  "meta": {
    "timestamp": "2026-02-26T12:00:00Z",
    "requestId": "req_abc123"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## List available OAuth scopes

`GET /workspaces/{id}/oauth/scopes`

- Auth: Bearer token
- Operation ID: `listWorkspaceOAuthScopes`

Get all available OAuth scopes that can be assigned to clients.

**Requires:** Workspace access

Scopes control what actions an OAuth client can perform.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/oauth/scopes \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Scopes retrieved successfully

```json
{
  "success": true,
  "data": {
    "scopes": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "scope": "transactions:read",
        "resource": "transactions",
        "action": "read",
        "description": "Read transaction data",
        "isActive": true
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "scope": "transactions:write",
        "resource": "transactions",
        "action": "write",
        "description": "Create and update transactions",
        "isActive": true
      }
    ]
  },
  "meta": {
    "timestamp": "2026-02-26T12:00:00Z",
    "requestId": "req_abc123"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error


---

# Customers (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/customers/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Global customer management (admin only)

## List all customers

`GET /customers`

- Auth: Bearer token
- Operation ID: `listCustomers`

Retrieve a paginated list of all customers across workspaces.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Page number (1-indexed) |
| `limit` | query | integer | no | Items per page |
| `workspaceId` | query | string (uuid) | no | Filter by workspace ID |
| `status` | query | enum ("active", "inactive", "suspended", "pending") | no | Filter by customer status |
| `search` | query | string | no | Search by name or email |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/customers \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Customers list retrieved successfully

```json
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "createdAt": "2026-01-20T08:30:00.000Z",
      "updatedAt": "2026-02-15T16:45:00.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 500,
      "totalPages": 25
    }
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Create a new customer

`POST /customers`

- Auth: Bearer token
- Operation ID: `createCustomer`

Create a new customer in a specified workspace.

**Permissions:** ADMIN or SUPER_ADMIN only

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `workspaceId` | string (uuid) | yes | Workspace ID to create customer in |
| `email` | string (email) | yes | Customer's email address |
| `firstName` | string | yes | Customer's first name |
| `lastName` | string | yes | Customer's last name |
| `phoneNumber` | string | no | Customer's phone number |
| `dateOfBirth` | string (date) | no | Customer's date of birth |
| `address` | string | no | Customer's street address |
| `city` | string | no | Customer's city |
| `state` | string | no | Customer's state/province |
| `postalCode` | string | no | Customer's postal code |
| `country` | string | no | Customer's country |
| `status` | enum ("active", "inactive", "suspended", "pending") | no | Initial customer status |
| `metadata` | object | no | Custom metadata |

```json
{
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1-555-123-4567",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94102",
  "country": "USA"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/customers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1-555-123-4567",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94102",
  "country": "USA"
}'
```

### Responses

**201** Customer created successfully

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "status": "active",
    "createdAt": "2026-02-24T12:00:00.000Z",
    "updatedAt": "2026-02-24T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Get customer by ID

`GET /customers/{id}`

- Auth: Bearer token
- Operation ID: `getCustomer`

Retrieve a customer by their unique identifier.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Customer UUID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/customers/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Customer found

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+1-555-123-4567",
    "status": "active",
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "emailVerified": true,
    "createdAt": "2026-01-20T08:30:00.000Z",
    "updatedAt": "2026-02-15T16:45:00.000Z"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Update customer

`PUT /customers/{id}`

- Auth: Bearer token
- Operation ID: `updateCustomer`

Update customer details.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | no | Customer's email address |
| `firstName` | string | no | Customer's first name |
| `lastName` | string | no | Customer's last name |
| `phoneNumber` | string | no | Customer's phone number |
| `dateOfBirth` | string (date) | no | Customer's date of birth |
| `address` | string | no | Customer's street address |
| `city` | string | no | Customer's city |
| `state` | string | no | Customer's state/province |
| `postalCode` | string | no | Customer's postal code |
| `country` | string | no | Customer's country |
| `status` | enum ("active", "inactive", "suspended", "pending") | no | Customer status |
| `metadata` | object | no | Custom metadata |

```json
{
  "firstName": "Jonathan",
  "lastName": "Doe",
  "phoneNumber": "+1-555-987-6543",
  "status": "active"
}
```

### Example request

```bash
curl -X PUT https://core-staging.coinbax.com/api/v1/customers/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Jonathan",
  "lastName": "Doe",
  "phoneNumber": "+1-555-987-6543",
  "status": "active"
}'
```

### Responses

**200** Customer updated successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "cust_12345",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+1-555-123-4567",
    "dateOfBirth": "1990-01-15",
    "address": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "USA",
    "status": "active",
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "emailVerified": true,
    "metadata": {
      "tier": "premium"
    },
    "createdAt": "2026-01-20T08:30:00.000Z",
    "updatedAt": "2026-02-15T16:45:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Delete customer

`DELETE /customers/{id}`

- Auth: Bearer token
- Operation ID: `deleteCustomer`

Permanently delete a customer.

**Permissions:** ADMIN or SUPER_ADMIN only

**Warning:** This action is irreversible.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/customers/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Customer deleted successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "message": "Customer deleted successfully"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Get customer Circle wallet

`GET /customers/{id}/circle-wallet`

- Auth: Bearer token
- Operation ID: `getCustomerCircleWallet`

Get the Circle wallet information for a customer.
Returns the wallet address and ID if the customer has a Circle wallet.

**Permissions:** Requires workspace access to the customer's workspace

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Customer UUID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/customers/<id>/circle-wallet \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Circle wallet information

```json
{
  "hasWallet": true,
  "walletId": "string",
  "walletAddress": "string",
  "walletLinkedAt": "2026-01-15T12:00:00.000Z"
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Provision Circle wallet for customer

`POST /customers/{id}/circle-wallet`

- Auth: Bearer token
- Operation ID: `createCustomerCircleWallet`

Provision a Circle wallet for a customer.
Creates a new wallet in the workspace's Circle wallet set.

**Prerequisites:**
- Workspace must have a Circle wallet provider configured
- Customer must not already have a Circle wallet

**Permissions:** Requires workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Customer UUID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `network` | enum ("BASE_SEPOLIA", "BASE", "ETH_SEPOLIA", "ETH") | no | Blockchain network for the wallet |

```json
{
  "network": "BASE_SEPOLIA"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/customers/<id>/circle-wallet \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "network": "BASE_SEPOLIA"
}'
```

### Responses

**201** Circle wallet created successfully

```json
{
  "success": true,
  "walletId": "string",
  "walletAddress": "string",
  "blockchain": "string",
  "createdAt": "2026-01-15T12:00:00.000Z"
}
```

**400** Bad request (customer already has wallet, workspace not configured)

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get customer Circle wallet balance

`GET /customers/{id}/circle-wallet/balance`

- Auth: Bearer token
- Operation ID: `getCustomerCircleWalletBalance`

Get the token balance for a customer's Circle wallet.

**Permissions:** Requires workspace access to the customer's workspace

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Customer UUID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/customers/<id>/circle-wallet/balance \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Wallet balance retrieved

```json
{
  "walletAddress": "string",
  "balances": [
    {
      "token": "USDC",
      "balance": "100.50",
      "network": "BASE_SEPOLIA"
    }
  ]
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get customer transactions

`GET /customers/{id}/transactions`

- Auth: Bearer token
- Operation ID: `getCustomerTransactions`

Retrieve transactions for a specific customer.

**Permissions:** Requires workspace access to the customer's workspace

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Customer UUID |
| `page` | query | integer | no |  |
| `limit` | query | integer | no |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/customers/<id>/transactions \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Customer transactions retrieved

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "transactions": [
      {
        "id": "tx_550e8400-e29b-41d4-a716-446655440000",
        "status": "COMPLETED",
        "amount": "100.00",
        "currency": "USDC",
        "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
        "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
        "blockchainNetwork": "base",
        "chainId": 8453,
        "txHash": "0xabcd...ef12",
        "orchestrationType": "raw",
        "metadata": {
          "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
          "customerId": "cust_12345"
        },
        "createdAt": "2026-02-24T10:00:00.000Z",
        "updatedAt": "2026-02-24T10:05:00.000Z",
        "_platformName": "Main Platform",
        "_platformId": "platform_xyz"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error


---

# Transactions (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/transactions/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Global transaction management

## List transactions

`GET /transactions`

- Auth: Bearer token
- Operation ID: `listTransactions`

Retrieve a paginated list of transactions. Transactions are aggregated from all
connected platforms (via platform mappings) or from the global API key.

**Filtering:**
- Filter by status, date range, addresses, wallet address

**Pagination:**
- Default: 20 items per page
- Max: 100 items per page

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Page number (1-indexed) |
| `limit` | query | integer | no | Items per page |
| `status` | query | enum ("PENDING", "ESCROWED", "IN_REVIEW", "COMPLETED", "FAILED", "CANCELLED") | no | Filter by transaction status |
| `dateFrom` | query | string (date-time) | no | Start date filter (ISO 8601) |
| `dateTo` | query | string (date-time) | no | End date filter (ISO 8601) |
| `fromAddress` | query | string | no | Filter by sender wallet address |
| `toAddress` | query | string | no | Filter by receiver wallet address |
| `walletAddress` | query | string | no | Filter by either sender or receiver address |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/transactions \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Transaction list retrieved successfully

```json
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "tx_abc123",
        "status": "COMPLETED",
        "amount": "100.00",
        "currency": "USDC",
        "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
        "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
        "blockchainNetwork": "base",
        "chainId": 8453,
        "txHash": "0xabcd...ef12",
        "createdAt": "2026-02-24T10:00:00.000Z",
        "_platformName": "Main Platform",
        "_platformId": "platform_xyz"
      }
    ],
    "meta": {
      "total": 150,
      "page": 1,
      "limit": 20,
      "totalPages": 8,
      "platformCount": 3
    }
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Get transaction by ID

`GET /transactions/{id}`

- Auth: Bearer token
- Operation ID: `getTransaction`

Retrieve a transaction by its unique identifier.

The transaction is searched across all connected platforms.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Transaction UUID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/transactions/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Transaction found

```json
{
  "success": true,
  "data": {
    "id": "tx_550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "amount": "100.00",
    "currency": "USDC",
    "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "blockchainNetwork": "base",
    "chainId": 8453,
    "txHash": "0xabcdef1234567890abcdef1234567890abcdef12345678901234567890abcdef12",
    "orchestrationType": "raw",
    "metadata": {
      "workspaceId": "123e4567-e89b-12d3-a456-426614174000"
    },
    "createdAt": "2026-02-24T10:00:00.000Z",
    "updatedAt": "2026-02-24T10:05:00.000Z",
    "_platformName": "Main Platform",
    "_platformId": "platform_xyz"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get transaction statistics

`GET /transactions/stats`

- Auth: Bearer token
- Operation ID: `getTransactionStats`

Retrieve aggregated transaction statistics across all connected platforms.

Returns counts and totals grouped by transaction status.

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/transactions/stats \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Transaction statistics retrieved successfully

```json
{
  "success": true,
  "data": {
    "COMPLETED": {
      "count": 1500,
      "total_amount": "150000.00"
    },
    "PENDING": {
      "count": 25,
      "total_amount": "2500.00"
    },
    "ESCROWED": {
      "count": 10,
      "total_amount": "1000.00"
    },
    "IN_REVIEW": {
      "count": 5,
      "total_amount": "500.00"
    },
    "FAILED": {
      "count": 15,
      "total_amount": "1500.00"
    },
    "CANCELLED": {
      "count": 8,
      "total_amount": "800.00"
    }
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error


---

# Users (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/users/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Admin user management

## List all users

`GET /users`

- Auth: Bearer token
- Operation ID: `listUsers`

Retrieve a paginated list of all users across workspaces.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no |  |
| `limit` | query | integer | no |  |
| `workspaceId` | query | string (uuid) | no | Filter by workspace |
| `role` | query | enum ("admin", "client") | no | Filter by role |
| `status` | query | enum ("active", "inactive", "suspended") | no | Filter by status |
| `search` | query | string | no | Search by name or email |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Users list retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "admin@coinbax.com",
      "firstName": "Admin",
      "lastName": "User",
      "role": "ADMIN",
      "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
      "emailVerified": true,
      "avatarPath": "/uploads/avatars/user-123.png",
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-02-20T14:30:00.000Z"
    }
  ]
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Create a new user

`POST /users`

- Auth: Bearer token
- Operation ID: `createUser`

Create a new user account.

**Permissions:** ADMIN or SUPER_ADMIN only

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `password` | string | yes |  |
| `firstName` | string | no |  |
| `lastName` | string | no |  |
| `role` | enum ("admin", "client") | yes |  |
| `workspaceId` | string (uuid) | no |  |

```json
{
  "email": "newuser@example.com",
  "password": "securePassword123",
  "firstName": "New",
  "lastName": "User",
  "role": "client",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "newuser@example.com",
  "password": "securePassword123",
  "firstName": "New",
  "lastName": "User",
  "role": "client",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000"
}'
```

### Responses

**201** User created successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@coinbax.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "emailVerified": true,
    "avatarPath": "/uploads/avatars/user-123.png",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**409** User with this email already exists

**500** Internal server error

---

## Get current user profile

`GET /users/me`

- Auth: Bearer token
- Operation ID: `getCurrentUser`

Retrieve the authenticated user's full profile information including workspace.

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/users/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** User profile retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@coinbax.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "emailVerified": true,
    "avatarPath": "/uploads/avatars/user-123.png",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Update current user profile

`PUT /users/me`

- Auth: Bearer token
- Operation ID: `updateCurrentUser`

Update the authenticated user's profile information.
Only firstName and lastName can be updated.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `firstName` | string | no |  |
| `lastName` | string | no |  |

```json
{
  "firstName": "Updated",
  "lastName": "Name"
}
```

### Example request

```bash
curl -X PUT https://core-staging.coinbax.com/api/v1/users/me \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Updated",
  "lastName": "Name"
}'
```

### Responses

**200** Profile updated successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@coinbax.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "emailVerified": true,
    "avatarPath": "/uploads/avatars/user-123.png",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Get user by ID

`GET /users/{id}`

- Auth: Bearer token
- Operation ID: `getUser`

Retrieve a user by their unique identifier.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/users/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** User found

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@coinbax.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "emailVerified": true,
    "avatarPath": "/uploads/avatars/user-123.png",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Update user

`PUT /users/{id}`

- Auth: Bearer token
- Operation ID: `updateUser`

Update user details.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | no |  |
| `password` | string | no |  |
| `firstName` | string | no |  |
| `lastName` | string | no |  |
| `role` | enum ("admin", "client") | no |  |
| `status` | enum ("active", "inactive", "suspended") | no |  |
| `workspaceId` | string (uuid) | no |  |

```json
{
  "email": "developer@example.com",
  "password": "string",
  "firstName": "string",
  "lastName": "string",
  "role": "admin",
  "status": "active",
  "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
}
```

### Example request

```bash
curl -X PUT https://core-staging.coinbax.com/api/v1/users/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "developer@example.com",
  "password": "string",
  "firstName": "string",
  "lastName": "string",
  "role": "admin",
  "status": "active",
  "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
}'
```

### Responses

**200** User updated successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@coinbax.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "emailVerified": true,
    "avatarPath": "/uploads/avatars/user-123.png",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Delete user

`DELETE /users/{id}`

- Auth: Bearer token
- Operation ID: `deleteUser`

Permanently delete a user.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/users/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** User deleted successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "message": "User deleted successfully"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Upload user avatar

`POST /users/me/avatar`

- Auth: Bearer token
- Operation ID: `uploadUserAvatar`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/users/me/avatar \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Uploaded

---

## Delete user avatar

`DELETE /users/me/avatar`

- Auth: Bearer token
- Operation ID: `deleteUserAvatar`

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/users/me/avatar \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**204** Deleted

---

## Update password

`PATCH /users/me/password`

- Auth: Bearer token
- Operation ID: `updateUserPassword`

### Example request

```bash
curl -X PATCH https://core-staging.coinbax.com/api/v1/users/me/password \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Updated

---

## Get user audit logs

`GET /users/{id}/audit-logs`

- Auth: Bearer token
- Operation ID: `getUserAuditLogs`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/users/<id>/audit-logs \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Retrieved


---

# Wallet Configs (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/wallet-configs/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Wallet provider configuration

## List external wallet configs

`GET /workspaces/{id}/external-wallet-configs`

- Auth: Bearer token
- Operation ID: `listExternalWalletConfigs`

Get all external wallet provider configurations for a workspace.
These configs determine which wallet providers (MetaMask, WalletConnect, etc.)
customers can use.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/external-wallet-configs \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** External wallet configs retrieved successfully

```json
{
  "configs": [
    {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "providerType": "METAMASK",
      "isEnabled": true,
      "allowedNetworks": [
        "BASE_SEPOLIA",
        "ETHEREUM_SEPOLIA"
      ],
      "allowedTemplateIds": [
        "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
      ],
      "config": {
        "infuraApiKey": "string",
        "projectId": "string",
        "appName": "string",
        "appLogoUrl": "string"
      },
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get external wallet config

`GET /workspaces/{id}/external-wallet-configs/{type}`

- Auth: Bearer token
- Operation ID: `getExternalWalletConfig`

Get a specific external wallet config by provider type.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `type` | path | enum ("METAMASK", "WALLET_CONNECT", "COINBASE_WALLET", "LEDGER") | yes | External wallet provider type |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/external-wallet-configs/<type> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** External wallet config retrieved successfully

```json
{
  "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "providerType": "METAMASK",
  "isEnabled": true,
  "allowedNetworks": [
    "BASE_SEPOLIA",
    "ETHEREUM_SEPOLIA"
  ],
  "allowedTemplateIds": [
    "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
  ],
  "config": {
    "infuraApiKey": "string",
    "projectId": "string",
    "appName": "string",
    "appLogoUrl": "string"
  },
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Create or update external wallet config

`PUT /workspaces/{id}/external-wallet-configs/{type}`

- Auth: Bearer token
- Operation ID: `updateExternalWalletConfig`

Create or update an external wallet provider configuration.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `type` | path | enum ("METAMASK", "WALLET_CONNECT", "COINBASE_WALLET", "LEDGER") | yes | External wallet provider type |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isEnabled` | boolean | no |  |
| `allowedNetworks` | array of string | no |  |
| `allowedTemplateIds` | array of string | no |  |
| `config` | object | no |  |

```json
{
  "isEnabled": true,
  "allowedNetworks": [
    "BASE_SEPOLIA",
    "ETHEREUM_SEPOLIA"
  ],
  "config": {
    "projectId": "your_wallet_connect_project_id"
  }
}
```

### Example request

```bash
curl -X PUT https://core-staging.coinbax.com/api/v1/workspaces/<id>/external-wallet-configs/<type> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "isEnabled": true,
  "allowedNetworks": [
    "BASE_SEPOLIA",
    "ETHEREUM_SEPOLIA"
  ],
  "config": {
    "projectId": "your_wallet_connect_project_id"
  }
}'
```

### Responses

**200** External wallet config updated successfully

```json
{
  "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "providerType": "METAMASK",
  "isEnabled": true,
  "allowedNetworks": [
    "BASE_SEPOLIA",
    "ETHEREUM_SEPOLIA"
  ],
  "allowedTemplateIds": [
    "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
  ],
  "config": {
    "infuraApiKey": "string",
    "projectId": "string",
    "appName": "string",
    "appLogoUrl": "string"
  },
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Delete external wallet config

`DELETE /workspaces/{id}/external-wallet-configs/{type}`

- Auth: Bearer token
- Operation ID: `deleteExternalWalletConfig`

Delete an external wallet provider configuration.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `type` | path | enum ("METAMASK", "WALLET_CONNECT", "COINBASE_WALLET", "LEDGER") | yes | External wallet provider type |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/workspaces/<id>/external-wallet-configs/<type> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** External wallet config deleted successfully

```json
{
  "message": "Config deleted successfully"
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error


---

# Notifications (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/notifications/
> Staging base URL: https://core-staging.coinbax.com/api/v1

User notifications

## List notifications

`GET /notifications`

- Auth: Bearer token
- Operation ID: `listNotifications`

Retrieve notifications for the authenticated user.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no |  |
| `limit` | query | integer | no |  |
| `unread` | query | boolean | no | Only return unread notifications |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/notifications \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Notifications retrieved successfully

```json
{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": "notif-uuid-1",
        "userId": "user-uuid",
        "type": "transaction",
        "priority": "normal",
        "title": "New Transaction",
        "message": "You received 100 USDC",
        "isRead": false,
        "createdAt": "2026-02-24T10:00:00.000Z"
      }
    ],
    "unreadCount": 5
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 50,
      "totalPages": 3
    }
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Delete all notifications

`DELETE /notifications`

- Auth: Bearer token
- Operation ID: `deleteAllNotifications`

Delete all notifications for the authenticated user.

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/notifications \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** All notifications deleted

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "message": "All notifications deleted successfully",
    "count": 25
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Mark notification as read

`PATCH /notifications/{id}/read`

- Auth: Bearer token
- Operation ID: `markNotificationAsRead`

Mark a specific notification as read.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X PATCH https://core-staging.coinbax.com/api/v1/notifications/<id>/read \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Notification marked as read

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "userId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "type": "info",
    "priority": "normal",
    "title": "New Transaction",
    "message": "You have a new incoming transaction",
    "isRead": false,
    "readAt": "2026-01-15T12:00:00.000Z",
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Mark all notifications as read

`POST /notifications/mark-all-read`

- Auth: Bearer token
- Operation ID: `markAllNotificationsAsRead`

Mark all notifications as read for the authenticated user.

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/notifications/mark-all-read \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** All notifications marked as read

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "message": "All notifications marked as read",
    "count": 10
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Get notification

`GET /notifications/{id}`

- Auth: Bearer token
- Operation ID: `getNotification`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/notifications/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Retrieved

---

## Get preferences

`GET /notifications/preferences`

- Auth: Bearer token
- Operation ID: `getNotificationPreferences`

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/notifications/preferences \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Retrieved

---

## Update preferences

`PATCH /notifications/preferences`

- Auth: Bearer token
- Operation ID: `updateNotificationPreferences`

### Example request

```bash
curl -X PATCH https://core-staging.coinbax.com/api/v1/notifications/preferences \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Updated


---

# Settings (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/settings/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Application settings

## List global settings

`GET /settings`

- Auth: Bearer token
- Operation ID: `listSettings`

Retrieve global settings. Encrypted values are returned as empty strings.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `category` | query | string | no | Filter by category |
| `page` | query | integer | no |  |
| `limit` | query | integer | no |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/settings \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Settings retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "settings": [
      {
        "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "key": "coinbax_api_key",
        "value": "",
        "category": "api",
        "description": "string",
        "isEncrypted": true,
        "createdAt": "2026-01-15T12:00:00.000Z",
        "updatedAt": "2026-01-15T12:00:00.000Z"
      }
    ],
    "meta": {
      "page": 100,
      "limit": 100,
      "total": 100,
      "totalPages": 100
    }
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Create or update global setting

`POST /settings`

- Auth: Bearer token
- Operation ID: `createSetting`

Create a new global setting or update an existing one.

**Permissions:** ADMIN or SUPER_ADMIN only

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | yes | Unique setting key |
| `value` | string | yes | Setting value |
| `category` | string | no | Setting category |
| `description` | string | no | Setting description |
| `isEncrypted` | boolean | no | Whether to encrypt the value |

```json
{
  "key": "custom_setting",
  "value": "setting_value",
  "category": "general",
  "description": "A custom setting",
  "isEncrypted": false
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/settings \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "custom_setting",
  "value": "setting_value",
  "category": "general",
  "description": "A custom setting",
  "isEncrypted": false
}'
```

### Responses

**201** Setting created successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "key": "coinbax_api_key",
    "value": "",
    "category": "api",
    "description": "string",
    "isEncrypted": true,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Get setting

`GET /settings/{key}`

- Auth: Bearer token
- Operation ID: `getSettingByKey`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `key` | path | string | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/settings/<key> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Retrieved

---

## Update setting

`PUT /settings/{key}`

- Auth: Bearer token
- Operation ID: `updateSetting`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `key` | path | string | yes |  |

### Example request

```bash
curl -X PUT https://core-staging.coinbax.com/api/v1/settings/<key> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Updated

---

## List global settings

`GET /global-settings`

- Auth: Bearer token
- Operation ID: `listGlobalSettings`

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/global-settings \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Retrieved

---

## Update settings bulk

`POST /global-settings/bulk`

- Auth: Bearer token
- Operation ID: `updateGlobalSettingsBulk`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/global-settings/bulk \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Updated


---

# Audit Logs (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/audit-logs/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Audit log access

## List workspace audit logs

`GET /workspaces/{id}/audit-logs`

- Auth: Bearer token
- Operation ID: `listWorkspaceAuditLogs`

Get audit logs for a workspace.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `page` | query | integer | no |  |
| `limit` | query | integer | no |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/audit-logs \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Audit logs retrieved successfully

```json
{
  "success": true,
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": [
    {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "userId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "action": "user.login",
      "resourceType": "user",
      "resourceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "details": "string",
      "changes": {},
      "success": true,
      "errorMessage": "string",
      "ipAddress": "string",
      "userAgent": "string",
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## List all audit logs

`GET /audit-logs`

- Auth: Bearer token
- Operation ID: `listAllAuditLogs`

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/audit-logs \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Audit logs retrieved

---

## Get audit log entry

`GET /audit-logs/{id}`

- Auth: Bearer token
- Operation ID: `getAuditLog`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/audit-logs/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Log retrieved

---

## Export audit logs

`GET /audit-logs/export`

- Auth: Bearer token
- Operation ID: `exportAuditLogs`

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/audit-logs/export \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Export file

---

## Get audit log statistics

`GET /audit-logs/stats`

- Auth: Bearer token
- Operation ID: `getAuditLogStats`

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/audit-logs/stats \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Statistics retrieved


---

# Smart Contracts (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/smart-contracts/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Smart contract management

## List contract deployments

`GET /workspaces/{id}/contracts`

- Auth: Bearer token
- Operation ID: `listWorkspaceContracts`

Get all contract deployments for a workspace.
Returns both dedicated and shared contract deployments.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/contracts \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Contract deployments retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": [
    {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "globalTemplateId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "network": "BASE_SEPOLIA",
      "contractType": "escrow",
      "contractAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "factoryAddress": "string",
      "deploymentTxHash": "string",
      "deployedAt": "2026-01-15T12:00:00.000Z",
      "deployedBy": "string",
      "status": "pending",
      "isShared": true,
      "verified": true,
      "verifiedAt": "2026-01-15T12:00:00.000Z",
      "metadata": {
        "gasUsed": 100,
        "blockNumber": 100,
        "deployerAddress": "string",
        "factoryVersion": "string"
      },
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get escrow contract address for network

`GET /workspaces/{id}/contracts/{network}`

- Auth: Bearer token
- Operation ID: `getWorkspaceContractByNetwork`

Get the escrow contract address for a workspace on a specific network.
Returns a dedicated contract if one exists, otherwise falls back to shared.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `network` | path | enum ("base-sepolia", "base", "ethereum-sepolia", "ethereum") | yes | Blockchain network |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/contracts/<network> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Contract address retrieved

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "address": "string",
    "network": "string",
    "isShared": true,
    "deploymentId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** No escrow contract deployed for network

**500** Internal server error

---

## Deploy dedicated escrow contract

`POST /workspaces/{id}/contracts/{network}`

- Auth: Bearer token
- Operation ID: `deployWorkspaceContract`

Deploy a dedicated escrow contract for a workspace on a specific network.
This will create a new WorkspaceEscrow contract via the factory.

**Permissions:** Admin only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `network` | path | enum ("base-sepolia", "base", "ethereum-sepolia", "ethereum") | yes | Blockchain network |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/contracts/<network> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**201** Contract deployed successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "deploymentId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "contractAddress": "string",
    "transactionHash": "string",
    "status": "PENDING",
    "network": "string",
    "gasUsed": "string",
    "blockNumber": 100
  }
}
```

**403** Forbidden - insufficient permissions

**404** Resource not found

**409** Workspace already has a dedicated contract

**500** Internal server error

**503** Deployment not available for network

---

## Deprecate contract deployment

`POST /workspaces/{id}/contracts/deployments/{deploymentId}/deprecate`

- Auth: Bearer token
- Operation ID: `deprecateContractDeployment`

Mark a contract deployment as deprecated.
Deprecated contracts will no longer be used for new transactions.

**Permissions:** Admin only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `deploymentId` | path | string (uuid) | yes | Contract deployment ID |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/contracts/deployments/<deploymentId>/deprecate \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Contract deprecated successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "globalTemplateId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "network": "BASE_SEPOLIA",
    "contractType": "escrow",
    "contractAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "factoryAddress": "string",
    "deploymentTxHash": "string",
    "deployedAt": "2026-01-15T12:00:00.000Z",
    "deployedBy": "string",
    "status": "pending",
    "isShared": true,
    "verified": true,
    "verifiedAt": "2026-01-15T12:00:00.000Z",
    "metadata": {
      "gasUsed": 100,
      "blockNumber": 100,
      "deployerAddress": "string",
      "factoryVersion": "string"
    },
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error


---

# Integrations (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/integrations/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Third-party integrations

## List workspace integrations

`GET /workspaces/{id}/integrations`

- Auth: Bearer token
- Operation ID: `listWorkspaceIntegrations`

Get all integrations enabled for a workspace.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/integrations \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Integrations retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": [
    {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "integrationId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "status": "active",
      "errorMessage": "string",
      "lastValidatedAt": "2026-01-15T12:00:00.000Z",
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Enable integration

`POST /workspaces/{id}/integrations`

- Auth: Bearer token
- Operation ID: `enableWorkspaceIntegration`

Enable an integration for a workspace.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `integrationId` | string (uuid) | yes | ID of the integration to enable |
| `config` | object | yes | Integration-specific configuration (API keys, etc.) |

```json
{
  "integrationId": "550e8400-e29b-41d4-a716-446655440000",
  "config": {
    "apiKey": "integration_api_key"
  }
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/integrations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "integrationId": "550e8400-e29b-41d4-a716-446655440000",
  "config": {
    "apiKey": "integration_api_key"
  }
}'
```

### Responses

**200** Integration enabled successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "integrationId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "status": "active",
    "errorMessage": "string",
    "lastValidatedAt": "2026-01-15T12:00:00.000Z",
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get integration details

`GET /workspaces/{id}/integrations/{integrationId}`

- Auth: Bearer token
- Operation ID: `getWorkspaceIntegration`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |
| `integrationId` | path | string (uuid) | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/integrations/<integrationId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Integration retrieved

---

## Remove integration

`DELETE /workspaces/{id}/integrations/{integrationId}`

- Auth: Bearer token
- Operation ID: `deleteWorkspaceIntegration`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |
| `integrationId` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/workspaces/<id>/integrations/<integrationId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**204** Removed

---

## Update integration

`PATCH /workspaces/{id}/integrations/{integrationId}`

- Auth: Bearer token
- Operation ID: `updateWorkspaceIntegration`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |
| `integrationId` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X PATCH https://core-staging.coinbax.com/api/v1/workspaces/<id>/integrations/<integrationId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Updated

---

## Disable integration

`POST /workspaces/{id}/integrations/{integrationId}/disable`

- Auth: Bearer token
- Operation ID: `disableWorkspaceIntegration`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |
| `integrationId` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/integrations/<integrationId>/disable \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Disabled

---

## Get integration status

`GET /workspaces/{id}/integrations/{integrationId}/status`

- Auth: Bearer token
- Operation ID: `getWorkspaceIntegrationStatus`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |
| `integrationId` | path | string (uuid) | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/integrations/<integrationId>/status \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Status retrieved

---

## Validate integration config

`POST /workspaces/{id}/integrations/validate`

- Auth: Bearer token
- Operation ID: `validateWorkspaceIntegration`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/integrations/validate \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Validated

---

## Enable integration with config

`POST /workspaces/{id}/integrations/with-config`

- Auth: Bearer token
- Operation ID: `enableWorkspaceIntegrationWithConfig`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/integrations/with-config \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**201** Enabled


---

# Health (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/health/
> Staging base URL: https://core-staging.coinbax.com/api/v1

System health checks

## Health check

`GET /health`

- Auth: Public (no authentication)
- Operation ID: `healthCheck`

Returns the health status of the API

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/health
```

### Responses

**200** Service is healthy

```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2026-02-24T12:00:00.000Z",
    "version": "1.0.0"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**500** Internal server error

---

## Database health check

`GET /health/database`

- Auth: Bearer token
- Operation ID: `healthCheckDatabase`

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/health/database \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Database is healthy

**503** Database is unhealthy

---

## Redis health check

`GET /health/redis`

- Auth: Bearer token
- Operation ID: `healthCheckRedis`

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/health/redis \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Redis is healthy

**503** Redis is unhealthy

---

## Storage health check

`GET /health/storage`

- Auth: Bearer token
- Operation ID: `healthCheckStorage`

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/health/storage \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Storage is healthy

**503** Storage is unhealthy


---

# Onboarding (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/onboarding/
> Staging base URL: https://core-staging.coinbax.com/api/v1

User onboarding flow

## Get onboarding status

`GET /onboarding`

- Auth: Bearer token
- Operation ID: `getOnboardingStatus`

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/onboarding \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Status

---

## Complete onboarding

`POST /onboarding/complete`

- Auth: Bearer token
- Operation ID: `completeOnboarding`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/onboarding/complete \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Completed

---

## Skip onboarding

`POST /onboarding/skip`

- Auth: Bearer token
- Operation ID: `skipOnboarding`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/onboarding/skip \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Skipped

---

## Create client

`POST /onboarding/create-client`

- Auth: Bearer token
- Operation ID: `onboardingCreateClient`

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/onboarding/create-client \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**201** Created


---

# Workspace Users (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/workspace-users/
> Staging base URL: https://core-staging.coinbax.com/api/v1

## List workspace users

`GET /workspaces/{id}/users`

- Auth: Bearer token
- Operation ID: `listWorkspaceUsers`

Retrieve a paginated list of users belonging to a specific workspace.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace UUID |
| `page` | query | integer | no |  |
| `limit` | query | integer | no |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Users list retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "admin@coinbax.com",
      "firstName": "Admin",
      "lastName": "User",
      "role": "ADMIN",
      "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
      "emailVerified": true,
      "avatarPath": "/uploads/avatars/user-123.png",
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-02-20T14:30:00.000Z"
    }
  ]
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Invite users to workspace

`POST /workspaces/me/invite-users`

- Auth: Bearer token
- Operation ID: `inviteWorkspaceUsers`

Invite team members to the authenticated user's workspace organization.
Creates user accounts and sends invitation emails with temporary passwords.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `users` | array of object | yes |  |

```json
{
  "users": [
    {
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    {
      "email": "jane.smith@example.com",
      "firstName": "Jane",
      "lastName": "Smith"
    }
  ]
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/me/invite-users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "users": [
    {
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    {
      "email": "jane.smith@example.com",
      "firstName": "Jane",
      "lastName": "Smith"
    }
  ]
}'
```

### Responses

**200** Invitation batch processed

```json
{
  "success": true,
  "data": {
    "invited": 2,
    "failed": 0,
    "users": [
      {
        "id": "uuid-1",
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe"
      },
      {
        "id": "uuid-2",
        "email": "jane.smith@example.com",
        "firstName": "Jane",
        "lastName": "Smith"
      }
    ]
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**500** Internal server error


---

# Workspace Wallets (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/workspace-wallets/
> Staging base URL: https://core-staging.coinbax.com/api/v1

## List wallet accounts

`GET /workspaces/{id}/wallet-accounts`

- Auth: Bearer token
- Operation ID: `listWorkspaceWalletAccounts`

Retrieve wallet accounts for a workspace from its configured wallet provider (Turnkey).

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace UUID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/wallet-accounts \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Wallet accounts retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "accounts": [
      {
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "addressFormat": "ADDRESS_FORMAT_ETHEREUM",
        "path": "m/44'/60'/0'/0/0",
        "curve": "CURVE_SECP256K1"
      }
    ],
    "message": "string"
  }
}
```

**400** Wallet provider not configured

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Create wallet accounts

`POST /workspaces/{id}/wallet-accounts`

- Auth: Bearer token
- Operation ID: `createWorkspaceWalletAccounts`

Create new wallet accounts for a workspace in its configured wallet provider (Turnkey).

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accounts` | array of object | yes |  |

```json
{
  "accounts": [
    {
      "addressFormat": "ADDRESS_FORMAT_ETHEREUM",
      "curve": "string",
      "path": "string"
    }
  ]
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/wallet-accounts \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accounts": [
    {
      "addressFormat": "ADDRESS_FORMAT_ETHEREUM",
      "curve": "string",
      "path": "string"
    }
  ]
}'
```

### Responses

**200** Wallet accounts created successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "accounts": [
      {
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "addressFormat": "ADDRESS_FORMAT_ETHEREUM",
        "path": "m/44'/60'/0'/0/0",
        "curve": "CURVE_SECP256K1"
      }
    ],
    "message": "string"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get wallet balances

`GET /workspaces/{id}/wallet-balances`

- Auth: Bearer token
- Operation ID: `getWorkspaceWalletBalances`

Retrieve blockchain balances for all wallet accounts in a workspace.
Fetches balances from both Solana and EVM networks with graceful degradation.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace UUID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/wallet-balances \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Wallet balances retrieved successfully

```json
{
  "success": true,
  "data": {
    "balances": [
      {
        "address": "0x1234...",
        "network": "base",
        "nativeBalance": "0.5",
        "nativeSymbol": "ETH",
        "tokens": [
          {
            "symbol": "USDC",
            "balance": "100.00",
            "contractAddress": "0xusdc..."
          }
        ]
      }
    ],
    "warnings": []
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**400** Wallet provider not configured

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error


---

# Wallet Provider Configs (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/wallet-provider-configs/
> Staging base URL: https://core-staging.coinbax.com/api/v1

## List wallet provider configurations

`GET /wallet-provider-configs`

- Auth: Bearer token
- Operation ID: `listWalletProviderConfigs`

Retrieve all wallet provider configurations.
Encrypted config values are never returned for security.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no |  |
| `limit` | query | integer | no |  |
| `isGlobal` | query | boolean | no |  |
| `workspaceId` | query | string (uuid) | no |  |
| `providerType` | query | enum ("TURNKEY", "CIRCLE", "FIREBLOCKS", "UTILA") | no |  |
| `isActive` | query | boolean | no |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/wallet-provider-configs \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Configurations retrieved successfully

```json
{
  "data": [
    {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "isGlobal": false,
      "providerType": "TURNKEY",
      "providerName": "Main Turnkey Account",
      "walletSetId": "string",
      "defaultWalletId": "string",
      "isActive": true,
      "isDefault": false,
      "supportedNetworks": [
        "ethereum",
        "base",
        "solana"
      ],
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  ],
  "total": 100,
  "page": 100,
  "limit": 100,
  "totalPages": 100
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Create wallet provider configuration

`POST /wallet-provider-configs`

- Auth: Bearer token
- Operation ID: `createWalletProviderConfig`

Create a new wallet provider configuration.
Global configs are not allowed - each workspace must configure its own provider.

**Permissions:** ADMIN or SUPER_ADMIN only

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `workspaceId` | string (uuid) | yes | Workspace ID (required, global configs not allowed) |
| `providerType` | enum ("TURNKEY", "CIRCLE", "FIREBLOCKS", "UTILA") | yes |  |
| `providerName` | string | yes |  |
| `walletSetId` | string | no |  |
| `defaultWalletId` | string | no |  |
| `config` | object | yes | Provider-specific credentials (encrypted at rest) |
| `isActive` | boolean | no |  |
| `isDefault` | boolean | no |  |
| `supportedNetworks` | array of string | no |  |
| `metadata` | object | no |  |

```json
{
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "providerType": "TURNKEY",
  "providerName": "Main Turnkey Account",
  "config": {
    "organizationId": "org_123",
    "apiPublicKey": "pk_...",
    "apiPrivateKey": "sk_..."
  },
  "supportedNetworks": [
    "ethereum",
    "base"
  ]
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/wallet-provider-configs \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "providerType": "TURNKEY",
  "providerName": "Main Turnkey Account",
  "config": {
    "organizationId": "org_123",
    "apiPublicKey": "pk_...",
    "apiPrivateKey": "sk_..."
  },
  "supportedNetworks": [
    "ethereum",
    "base"
  ]
}'
```

### Responses

**201** Configuration created successfully

```json
{
  "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "isGlobal": false,
  "providerType": "TURNKEY",
  "providerName": "Main Turnkey Account",
  "walletSetId": "string",
  "defaultWalletId": "string",
  "isActive": true,
  "isDefault": false,
  "supportedNetworks": [
    "ethereum",
    "base",
    "solana"
  ],
  "metadata": {},
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Get wallet provider configuration

`GET /wallet-provider-configs/{id}`

- Auth: Bearer token
- Operation ID: `getWalletProviderConfig`

Retrieve a specific wallet provider configuration.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/wallet-provider-configs/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Configuration found

```json
{
  "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "isGlobal": false,
  "providerType": "TURNKEY",
  "providerName": "Main Turnkey Account",
  "walletSetId": "string",
  "defaultWalletId": "string",
  "isActive": true,
  "isDefault": false,
  "supportedNetworks": [
    "ethereum",
    "base",
    "solana"
  ],
  "metadata": {},
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Delete wallet provider configuration

`DELETE /wallet-provider-configs/{id}`

- Auth: Bearer token
- Operation ID: `deleteWalletProviderConfig`

Delete a wallet provider configuration.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/wallet-provider-configs/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**204** Configuration deleted successfully

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Update wallet provider configuration

`PATCH /wallet-provider-configs/{id}`

- Auth: Bearer token
- Operation ID: `updateWalletProviderConfig`

Update a wallet provider configuration.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `providerName` | string | no |  |
| `config` | object | no |  |
| `isActive` | boolean | no |  |
| `isDefault` | boolean | no |  |
| `supportedNetworks` | array of string | no |  |
| `metadata` | object | no |  |

```json
{
  "providerName": "string",
  "config": {},
  "isActive": true,
  "isDefault": true,
  "supportedNetworks": [
    "string"
  ],
  "metadata": {}
}
```

### Example request

```bash
curl -X PATCH https://core-staging.coinbax.com/api/v1/wallet-provider-configs/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "providerName": "string",
  "config": {},
  "isActive": true,
  "isDefault": true,
  "supportedNetworks": [
    "string"
  ],
  "metadata": {}
}'
```

### Responses

**200** Configuration updated successfully

```json
{
  "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "isGlobal": false,
  "providerType": "TURNKEY",
  "providerName": "Main Turnkey Account",
  "walletSetId": "string",
  "defaultWalletId": "string",
  "isActive": true,
  "isDefault": false,
  "supportedNetworks": [
    "ethereum",
    "base",
    "solana"
  ],
  "metadata": {},
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Test wallet provider connection

`POST /wallet-provider-configs/{id}/test-connection`

- Auth: Bearer token
- Operation ID: `testWalletProviderConnection`

Test the connection to a wallet provider using the stored configuration.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/wallet-provider-configs/<id>/test-connection \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Connection test result

```json
{
  "success": true,
  "message": "string",
  "details": {}
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Get wallet provider config status

`GET /wallet-provider-configs/status`

- Auth: X-API-Key header
- Operation ID: `getWalletProviderConfigStatus`

Returns the status and version of all active wallet provider configs.
This endpoint is used by coinbax-api for cache invalidation.

**Authentication:** X-Internal-API-Key header (internal service-to-service calls only)

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/wallet-provider-configs/status \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Configuration status retrieved

```json
{
  "configs": [
    {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "isGlobal": true,
      "providerType": "string",
      "providerName": "string",
      "version": 100,
      "isActive": true,
      "isDefault": true,
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  ],
  "total": 100,
  "timestamp": "2026-01-15T12:00:00.000Z"
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Check for duplicate wallet provider config

`GET /wallet-provider-configs/check-duplicate`

- Auth: Bearer token
- Operation ID: `checkDuplicateWalletProviderConfig`

Check if a wallet provider config with the same provider type exists.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `providerType` | query | enum ("CIRCLE", "TURNKEY") | yes |  |
| `workspaceId` | query | string (uuid) | no |  |
| `excludeId` | query | string (uuid) | no |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/wallet-provider-configs/check-duplicate?providerType=<providerType> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Duplicate check result

```json
{
  "isDuplicate": true,
  "existingConfig": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "isGlobal": false,
    "providerType": "TURNKEY",
    "providerName": "Main Turnkey Account",
    "walletSetId": "string",
    "defaultWalletId": "string",
    "isActive": true,
    "isDefault": false,
    "supportedNetworks": [
      "ethereum",
      "base",
      "solana"
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Set wallet provider config as default

`POST /wallet-provider-configs/{id}/set-default`

- Auth: Bearer token
- Operation ID: `setDefaultWalletProviderConfig`

Set a wallet provider configuration as the default for its scope.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/wallet-provider-configs/<id>/set-default \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Config set as default successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "isGlobal": false,
    "providerType": "TURNKEY",
    "providerName": "Main Turnkey Account",
    "walletSetId": "string",
    "defaultWalletId": "string",
    "isActive": true,
    "isDefault": false,
    "supportedNetworks": [
      "ethereum",
      "base",
      "solana"
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Get effective wallet provider configuration

`GET /wallet-provider-configs/effective`

- Auth: Bearer token
- Operation ID: `getEffectiveWalletProviderConfig`

Get the effective (currently active) wallet provider configuration.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | query | string (uuid) | no | Workspace to get effective config for |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/wallet-provider-configs/effective \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Effective configuration found

```json
{
  "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "isGlobal": false,
  "providerType": "TURNKEY",
  "providerName": "Main Turnkey Account",
  "walletSetId": "string",
  "defaultWalletId": "string",
  "isActive": true,
  "isDefault": false,
  "supportedNetworks": [
    "ethereum",
    "base",
    "solana"
  ],
  "metadata": {},
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** No effective configuration found

**500** Internal server error