Custody Accounts

POST

/custody/accounts

Creates a new custody account that can be used for managing cryptocurrency assets. The custody account is associated with the current tenant and can be used for deposits, withdrawals, and transfers.

Request Parameters

Parameter	Type	Description
name required	string	A descriptive name for the custody account
provider optional	string	The custody provider to use.
account_type optional	string	Type of account (e.g., "standard", "hot", "cold"). Default is "standard"
metadata optional	object	Additional metadata for the account in key-value format

Example Request

POST /custody/accounts
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "name": "Main Trading Account",
  "account_type": "standard",
  "metadata": {
    "description": "Primary account for processing customer payments"
  }
}

Response Parameters

Parameter	Type	Description
account_id	string	Unique identifier for the custody account
name	string	The name of the custody account
provider	string	The custody provider being used
account_type	string	The type of account
status	string	Current status of the account (e.g., "active")
created_at	string	ISO 8601 timestamp of when the account was created
metadata	object	Additional metadata for the account

Example Response

{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Main Trading Account",
  "account_type": "standard",
  "status": "active",
  "created_at": "2025-04-16T13:30:25.123Z",
  "metadata": {
    "description": "Primary account for processing customer payments"
  }
}

Error Codes

Status Code	Error Code	Description
400	invalid_request	The request was malformed or contained invalid parameters
401	authentication_failed	Authentication failed. Check your API key or JWT token
403	insufficient_permissions	You do not have permission to create custody accounts
429	rate_limit_exceeded	You have exceeded the rate limit for this endpoint
500	custody_provider_error	An error occurred with the custody provider

Notes

• A tenant can have multiple custody accounts for different purposes
• Each custody account can hold balances across multiple blockchains
• The account will be immediately available for generating deposit addresses

GET

/custody/accounts

Returns a list of all custody accounts belonging to the current tenant.

Query Parameters

Parameter	Type	Description
skip optional	integer	Number of records to skip for pagination. Default: 0
limit optional	integer	Maximum number of records to return. Default: 10, Maximum: 100
status optional	string	Filter by account status (e.g., "active", "inactive")

Example Request

GET /custody/accounts?limit=5&skip=0&status=active
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response

[
  {
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Main Trading Account",
      "account_type": "standard",
    "status": "active",
    "created_at": "2025-04-16T13:30:25.123Z",
    "metadata": {
      "description": "Primary account for processing customer payments"
    }
  },
  {
    "account_id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Secondary Account",
      "account_type": "hot",
    "status": "active",
    "created_at": "2025-04-16T14:45:30.456Z",
    "metadata": {
      "description": "Secondary account for automated withdrawals"
    }
  }
]

Error Codes

Status Code	Error Code	Description
401	authentication_failed	Authentication failed. Check your API key or JWT token
403	insufficient_permissions	You do not have permission to list custody accounts
429	rate_limit_exceeded	You have exceeded the rate limit for this endpoint

GET

/custody/accounts/:accountId

Returns detailed information about a specific custody account.

Path Parameters

Parameter	Type	Description
accountId required	string	The unique identifier of the custody account

Example Request

GET /custody/accounts/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response

{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Main Trading Account",
  "account_type": "standard",
  "status": "active",
  "created_at": "2025-04-16T13:30:25.123Z",
  "updated_at": "2025-04-16T14:45:30.456Z",
  "metadata": {
    "description": "Primary account for processing customer payments"
  },
  "balances_summary": {
    "total_usd": 15240.50,
    "blockchains": [
      {
        "blockchain": "ETH",
        "token": "USDT",
        "balance": 10000.00,
        "usd_value": 10000.00
      },
      {
        "blockchain": "BSC",
        "token": "USDT",
        "balance": 5240.50,
        "usd_value": 5240.50
      }
    ]
  }
}

Error Codes

Status Code	Error Code	Description
401	authentication_failed	Authentication failed. Check your API key or JWT token
403	insufficient_permissions	You do not have permission to view this custody account
404	account_not_found	Custody account with the specified ID was not found
429	rate_limit_exceeded	You have exceeded the rate limit for this endpoint