Account Service

Manages user accounts.

---

Endpoints

---

Create Account

POST /accounts

Create a new account for a customer.

Request Body

Field	Type	Required	Description	Example
customerId	string	No	Customer UUID. Must be a valid UUID.	"eac6de80-8a71-4dc3-abee-240214cea9d5"
customerExternalId	string	No	External customer ID for integration with external systems.	"external-customer-id-123"
walletAccountId	string	No	Wallet account UUID. Must be a valid UUID.	"wallet-uuid-123"
accountExternalId	string	No	External account ID for integration with external systems.	"external-account-id-456"
type	enum	Yes	Type of account. Must be one of: STABLECOINS, ... (see AccountType enum).	"STABLECOINS"
status	enum	Yes	Account status. Must be one of: active, inactive, deleted, suspended.	"active"
name	string	Yes	Account name. Must be 1-100 characters.	"Main Account"
customerName	string	No	Customer name.	"John Doe"

Example Request:

{
  "customerId": "eac6de80-8a71-4dc3-abee-240214cea9d5",
  "customerExternalId": "external-customer-id-123",
  "walletAccountId": "wallet-uuid-123",
  "accountExternalId": "external-account-id-456",
  "type": "STABLECOINS",
  "status": "active",
  "name": "Main Account",
  "customerName": "John Doe"
}

Success Response

Returns the created account object.

{
  "id": "b2c3d4e5-f678-90ab-cd12-34567890abcd",
  "customerId": "eac6de80-8a71-4dc3-abee-240214cea9d5",
  "customerExternalId": "external-customer-id-123",
  "walletAccountId": "wallet-uuid-123",
  "accountExternalId": "external-account-id-456",
  "type": "STABLECOINS",
  "status": "active",
  "name": "Main Account",
  "customerName": "John Doe",
  "createdAt": "2025-11-18T12:34:56.789Z"
}

Error Responses

• 400 Bad Request: Validation failed (missing or invalid fields)
• 409 Conflict: Duplicate external/customer/account ID
• 404 Not Found: Referenced customer or wallet does not exist

---

List Accounts

GET /accounts

Retrieve all accounts, with optional filters.

Query Parameters

Parameter	Type	Description
filter	object	Filter object. Supports address, id, externalId fields.

Example:

/accounts?filter[address]=in:0x123,0x456&filter[id]=in:uuid1,uuid2&filter[externalId]=eq:ext-12345

Success Response

Returns an array of account objects.

[
  {
    "id": "b2c3d4e5-f678-90ab-cd12-34567890abcd",
    "customerId": "eac6de80-8a71-4dc3-abee-240214cea9d5",
    "customerExternalId": "external-customer-id-123",
    "walletAccountId": "wallet-uuid-123",
    "accountExternalId": "external-account-id-456",
    "type": "STABLECOINS",
    "status": "active",
    "name": "Main Account",
    "customerName": "John Doe",
    "createdAt": "2025-11-18T12:34:56.789Z"
  }
  // ...more accounts
]

---

Get or Create Omnibus Account

GET /accounts/omnibus

Get or create the omnibus account for the authenticated participant.

Success Response

Returns the omnibus account object (same fields as above).

Error Responses

• 401 Unauthorized: Participant not found in request

---

Get or Create Fee Payer Account

GET /accounts/fee-payer

Get or create the fee payer account for the authenticated participant.

Success Response

Returns the fee payer account object (same fields as above).

Error Responses

• 401 Unauthorized: Participant not found in request

---

Get Account

GET /accounts/:id

Retrieve details for a specific account.

Path Parameters

Parameter	Type	Required	Description
id	uuid	Yes	Account unique ID

Success Response

{
  "id": "b2c3d4e5-f678-90ab-cd12-34567890abcd",
  "customerId": "eac6de80-8a71-4dc3-abee-240214cea9d5",
  "customerExternalId": "external-customer-id-123",
  "walletAccountId": "wallet-uuid-123",
  "accountExternalId": "external-account-id-456",
  "type": "STABLECOINS",
  "status": "active",
  "name": "Main Account",
  "customerName": "John Doe",
  "createdAt": "2025-11-18T12:34:56.789Z"
}

Error Responses

• 404 Not Found: Account not found

---

Update Account

PUT /accounts/:id

Update the status of an existing account.

Path Parameters

Parameter	Type	Required	Description
id	uuid	Yes	Account unique ID

Request Body

Field	Type	Required	Description	Example
status	enum	Yes	Account status to update. Must be one of: active, inactive, deleted, suspended.	"active"

Example Request:

{
  "status": "active"
}

Success Response

Returns the updated account object.

{
  "id": "b2c3d4e5-f678-90ab-cd12-34567890abcd",
  "customerId": "eac6de80-8a71-4dc3-abee-240214cea9d5",
  "customerExternalId": "external-customer-id-123",
  "walletAccountId": "wallet-uuid-123",
  "accountExternalId": "external-account-id-456",
  "type": "STABLECOINS",
  "status": "active",
  "name": "Main Account",
  "customerName": "John Doe",
  "createdAt": "2025-11-18T12:34:56.789Z"
}

Error Responses

• 400 Bad Request: Validation failed
• 404 Not Found: Account not found

---

Get All Addresses for Account

GET /accounts/:id/addresses

Retrieve all blockchain addresses associated with an account.

Path Parameters

Parameter	Type	Required	Description
id	uuid	Yes	Account unique ID

Success Response

Returns an array of addresses.

[
  "0x1234567890abcdef...",
  "0xabcdef1234567890..."
]

Error Responses

• 404 Not Found: Account not found
• 400 Bad Request: Invalid account ID format

---

Get Account Balance

GET /accounts/:id/balance

Get the account's balance, with asset breakdown in USD.

Path Parameters

Parameter	Type	Required	Description
id	uuid	Yes	Account unique ID

Success Response

{
  "accountId": "eac6de80-8a71-4dc3-abee-240214cea9d5",
  "currency": "USD",
  "totalBalance": 1000,
  "assets": [
    {
      "asset": { "symbol": "USDC", "name": "USD Coin", "decimals": 6 },
      "quantity": 1000,
      "usdValue": 1000,
      "usdQuoteTimestamp": "2025-10-31T12:00:00Z",
      "usdQuoteRate": 1
    },
    {
      "asset": { "symbol": "ETH", "name": "Ethereum", "decimals": 18 },
      "quantity": 0.25,
      "usdValue": 500,
      "usdQuoteTimestamp": "2025-10-31T12:00:00Z",
      "usdQuoteRate": 2000
    }
  ],
  "timestamp": "2025-10-31T12:00:00Z"
}

Error Responses

• 404 Not Found: Account not found
• 400 Bad Request: Invalid account ID format
• 500 Internal Server Error: Failed to retrieve account balance

---

Delete Account

DELETE /accounts/:id

Note: Account deletion is not permitted. This endpoint will always return a 405 Method Not Allowed error.

Error Response

• 405 Method Not Allowed: Account deletion is not permitted

---

Error Format

All error responses follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Description of the error",
    "details": [
      {
        "field": "fieldName",
        "message": "Field-specific error message"
      }
    ]
  }
}

---

Field Descriptions

Field	Type	Description
id	uuid	Unique identifier for the account
customerId	uuid	Customer UUID
customerExternalId	string	External customer ID
walletAccountId	uuid	Wallet account UUID
accountExternalId	string	External account ID
type	enum	Account type (see AccountType enum)
status	enum	Account status (see AccountStatus enum)
name	string	Account name
customerName	string	Customer name
createdAt	string	ISO8601 timestamp of account creation

---

For enum values, see AccountType and AccountStatus definitions.