# 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