# 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