# 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