Skip to main content
POST
/
platform
/
admin
/
custodians
Create custodian with wallets
curl --request POST \
  --url https://api.example.com/platform/admin/custodians \
  --header 'Content-Type: application/json' \
  --data '
{
  "tenantId": 1024,
  "provider": "Fireblocks",
  "accountName": "Alpha Treasury Desk",
  "apiKey": "b272c1a6-3c5f-4d35-904d-8f7127debf25",
  "secretApiKey": "super-secret-key",
  "isAllowedContractOwnership": true,
  "isAllowedTreasuryOperations": true,
  "isVisibleWallet": true,
  "isActiveWallet": true,
  "isActiveCustodialRelationship": true,
  "isActiveTreasuryWallets": false,
  "requestId": "1e2f6d7c-8a91-4bc3-951f-12d34f56a789"
}
'
{
  "isSuccess": true,
  "isFailure": false,
  "error": null,
  "value": {
    "id": 42,
    "name": "Example"
  }
}

​
Description

Registers a new custodian provider (such as Fireblocks) in the platform, validates API credentials, and performs initial wallet synchronization from the provider. Applies default settings for wallet visibility, active status, and operational permissions.

​
Input

Expects a JSON body containing:
  • tenantId (long, required) — Identifier of the tenant.
  • provider (string, required) — Name of the custody provider (e.g., “Fireblocks”).
  • accountName (string, required) — Display name for the custodian account.
  • apiKey (string, required) — API key for provider authentication.
  • secretApiKey (string, required) — Secret key for provider authentication.
  • isAllowedContractOwnership (bool, required) — Whether wallets can own smart contracts.
  • isAllowedTreasuryOperations (bool, required) — Whether treasury operations are permitted.
  • isVisibleWallet (bool, required) — Default visibility setting for synchronized wallets.
  • isActiveWallet (bool, required) — Default active status for synchronized wallets.
  • isActiveCustodialRelationship (bool, required) — Whether the custodial relationship is active.
  • isActiveTreasuryWallets (bool, required) — Whether treasury wallet features are enabled.
  • requestId (string, optional) — Idempotency key for the operation.

​
Output

Returns a response object containing:
  • custodianId (long) — Unique identifier of the newly created custodian.
  • walletsImported (int) — Number of wallets synchronized from the provider.

​
Examples

Request 
{
  "tenantId": 1024,
  "provider": "Fireblocks",
  "accountName": "Production Treasury",
  "apiKey": "9c5e7b3a-2d1f-4e8a-9b7c-5f3e2a1d4c6b",
  "secretApiKey": "MIICXAIBAAKBgQC...",
  "isAllowedContractOwnership": true,
  "isAllowedTreasuryOperations": true,
  "isVisibleWallet": true,
  "isActiveWallet": true,
  "isActiveCustodialRelationship": true,
  "isActiveTreasuryWallets": false,
  "requestId": "7d4f9e2a-5c8b-4e1a-9f7d-3e5b2c1a4f6d"
}
Response (200 OK) 
{
  "data": {
    "custodianId": 42,
    "walletsImported": 15
  },
  "isSuccess": true
}

​
Errors

  • 400 Bad Request: Invalid payload, missing required fields, or invalid credentials.
  • 401 Unauthorized: Authentication required but not provided.
  • 403 Forbidden: Caller does not have permission to create custodians.
  • 409 Conflict: Custodian with same provider and account name already exists for this tenant.
  • 500 Internal Server Error: Connection to provider failed or unexpected error occurred.

​
Notes

This endpoint performs both custodian creation and initial wallet synchronization. The API credentials are validated against the external provider before creation. Use the requestId for idempotent operations to prevent duplicate custodians.

Query Parameters

​
api-version
string | null

Body

application/json

The request containing tenant identifier, provider configuration, API credentials, and wallet sync settings.

Request to create a new custodian integration with wallet synchronization configuration.

​
tenantId
integer<int64>

Identifier of the tenant creating the custodian.

Example:

1024

​
provider
enum<string>

Provider selected during the initial step of the wizard.

Available options:
Unknown,
Fireblocks,
Venly,
Bitgo,
AnchorageDigital,
CoinbaseCustody,
FireblocksSandbox
Example:

"Fireblocks"

​
accountName
string

Custodian account name supplied by the tenant.

Example:

"Alpha Treasury Desk"

​
apiKey
string

Primary API key used to authenticate with the provider.

Example:

"b272c1a6-3c5f-4d35-904d-8f7127debf25"

​
secretApiKey
string

Secret API key or credential paired with the primary API key.

Example:

"super-secret-key"

​
isAllowedContractOwnership
boolean

Flag indicating whether contract ownership should be enabled.

Example:

true

​
isAllowedTreasuryOperations
boolean

Flag indicating whether treasury operations should be enabled.

Example:

true

​
isVisibleWallet
boolean

Flag indicating whether wallets should be visible after creation.

Example:

true

​
isActiveWallet
boolean

Flag indicating whether wallets should be active after creation.

Example:

true

​
isActiveCustodialRelationship
boolean

Flag indicating whether the custodial relationship should be active.

Example:

true

​
isActiveTreasuryWallets
boolean

Flag indicating whether treasury wallets should be active.

Example:

false

​
requestId
string<guid>

Correlation identifier reused between wizard steps to reuse cached provider data.

Example:

"1e2f6d7c-8a91-4bc3-951f-12d34f56a789"

Response

Custodian created successfully.

Wrapper for API operation results containing success status, error information, and return value.

​
isSuccess
boolean

True if the operation completed successfully, false otherwise.

Example:

true

​
isFailure
boolean

True if the operation failed, false otherwise.

Example:

false

​
error
object

Error information returned when the operation fails.

Example:
{
  "code": "ValidationError",
  "message": "The request parameters failed validation.",
  "info": [
    "The Name field is required.",
    "The Id field must be greater than 0."
  ]
}
​
value
object

The result value returned when the operation is successful.

Example:
{ "id": 128, "isWrongCredentials": false }