Subaccounts
Subaccounts Endpoints
Overview
The Subaccounts endpoints provide comprehensive portfolio management capabilities for August Digital users. These endpoints allow you to manage multi-chain DeFi portfolios, monitor health factors, execute swaps, and track positions across various protocols and exchanges.
Authentication
All subaccounts endpoints require API key authentication:
x-api-key: YOUR_API_KEY
Account Discovery
Get My Subaccounts
Endpoint: GET /subaccounts
Retrieve a list of all subaccounts associated with your API key.
Authentication Required
โ Yes - API Key Header required
Response
Returns an array of subaccount objects containing:
Subaccount address and name
Current status (active, inactive, etc.)
Supported blockchain networks
Basic account metadata
Use Cases
Dashboard account selection interfaces
Portfolio overview screens
Account management and organization
Multi-account navigation
Portfolio Analytics
Get Subaccount Summary
Endpoint: GET /subaccounts/summary
Get comprehensive portfolio information for a specific subaccount including all positions, balances, and analytics.
Authentication Required
โ Yes - API Key Header required
Parameters
address
(required): The subaccount address to retrieve summary for
Response
Returns detailed portfolio data including:
Portfolio Holdings:
Token balances with USD values
Margin and collateral positions
DeFi protocol positions (lending, liquidity providing)
CEX (centralized exchange) positions
TRS (Total Return Swap) positions
Legacy strategy and hedger positions
Account Metrics:
Total account value
Total collateral value
Total loan value
Net account value
Health factor calculations
Total equity value
Risk Management:
Loan book with active loans
Credit and debt positions by token
Health factor monitoring
Liquidation risk assessment
Use Cases
Complete portfolio dashboards
Risk management interfaces
Position tracking and analysis
Performance monitoring
Regulatory reporting
Successful Response
Validation Error
GET /api/v1/subaccounts/summary?address=text HTTP/1.1
Host:
x-api-key: YOUR_API_KEY
Accept: */*
{
"address": "text",
"name": "text",
"portfolio": {
"tokens": [
{
"value": 1,
"balance": 1,
"token": {
"type": "fiat",
"name": "text",
"address": "text",
"chain": 1,
"symbol": "text",
"decimals": 1,
"img_url": "text"
}
}
],
"margin_balances": [
{
"value": 1,
"balance": 1,
"token": {
"type": "fiat",
"name": "text",
"address": "text",
"chain": 1,
"symbol": "text",
"decimals": 1,
"img_url": "text"
}
}
],
"collateral_balances": [
{
"value": 1,
"balance": 1,
"token": {
"type": "fiat",
"name": "text",
"address": "text",
"chain": 1,
"symbol": "text",
"decimals": 1,
"img_url": "text"
}
}
],
"cefi_positions": [
{
"value": 1,
"name": "text",
"spot_tokens": [
{
"asset": {
"type": "fiat",
"name": "text",
"underlying": "text",
"symbol": "text",
"asset_type": "text"
},
"value": 1,
"balance": 1
}
],
"derivative_positions": [
{
"value": 1,
"asset_type": "text",
"asset": {
"type": "fiat",
"name": "text",
"underlying": "text",
"symbol": "text",
"asset_type": "text"
},
"units": 1,
"avg_cost": 1,
"margin": 0,
"entry_cost": 1
}
]
}
],
"defi_positions": [
{
"value": 1,
"name": "text",
"chain": 1,
"tokens": {
"supply_tokens": [
{
"value": 1,
"balance": 1,
"token": {
"type": "fiat",
"name": "text",
"address": "text",
"chain": 1,
"symbol": "text",
"decimals": 1,
"img_url": "text"
}
}
],
"reward_tokens": [
{
"value": 1,
"balance": 1,
"token": {
"type": "fiat",
"name": "text",
"address": "text",
"chain": 1,
"symbol": "text",
"decimals": 1,
"img_url": "text"
}
}
],
"borrow_tokens": [
{
"value": 1,
"balance": 1,
"token": {
"type": "fiat",
"name": "text",
"address": "text",
"chain": 1,
"symbol": "text",
"decimals": 1,
"img_url": "text"
}
}
]
},
"health_factor": 1
}
],
"trs_positions": [
{
"value": 1,
"token": {
"type": "fiat",
"name": "text",
"address": "text",
"chain": 1,
"symbol": "text",
"decimals": 1,
"img_url": "text"
},
"contract_address": "text",
"chain": 1,
"payer": "text",
"receiver": "text",
"balance": 1,
"entry_cost": 1,
"initial_price": 1
}
],
"strategy_contract_positions": [
{
"value": 1,
"name": "text",
"chain": 1,
"balances": [
{
"value": 1,
"balance": 1,
"token": {
"type": "fiat",
"name": "text",
"address": "text",
"chain": 1,
"symbol": "text",
"decimals": 1,
"img_url": "text"
}
}
]
}
],
"legacy_hedger_positions": [
{
"value": 1,
"payers": [
"text"
],
"pnl": 1
}
],
"otc_positions": [
{}
],
"total_value": 1,
"discounted_value": 1
},
"loanbook": {
"loans": [
{
"subaccount_address": "text",
"book": {
"address": "text",
"lender": "text",
"borrower": "text",
"state": "PREAPPROVED",
"total_repaid": 1,
"principal_token": {
"chain": 1,
"name": "text",
"token_type": 0,
"address": "text",
"decimals": 1,
"symbol": "text",
"discount_factor": 0,
"img_url": "text",
"price": 1
},
"principal_amount": 1,
"interest_amount": 1,
"upcoming_payment": {
"amount": 1,
"due_date": "2025-08-09T00:58:13.765Z"
},
"apr": 1,
"initial_principal_amount": 1,
"deployed_date": "2025-08-09T00:58:13.765Z",
"payment_interval": 1,
"total_interest_payment_fees": 1
},
"is_borrow": true,
"debt_info": {
"interest_owed": 1,
"principal_debt_owed": 1,
"interest_repaid": 1
},
"credit_info": {
"net_interest_owed": 1,
"principal_debt_owed": 1,
"net_interest_repaid": 1
}
}
],
"total_debt": 1,
"total_credit": 1,
"aggregates_by_token": [
{
"token": {
"type": "fiat",
"name": "text",
"address": "text",
"chain": 1,
"symbol": "text",
"decimals": 1,
"img_url": "text"
},
"total_credit_value": 1,
"total_debt_value": 1,
"total_credit_balance": 1,
"total_debt_balance": 1
}
]
},
"chains": [
{
"name": "text",
"chain_id": 1
}
],
"tokens": [
{
"type": "fiat",
"name": "text",
"address": "text",
"chain": 1,
"symbol": "text",
"decimals": 1,
"img_url": "text",
"price": 1,
"raw_balance": 1,
"balance": 1,
"value": 1
}
],
"total_account_value": 1,
"total_collateral_value": 1,
"total_loan_value": 1,
"health_factor": 1,
"net_account_value": 1,
"total_equity_value": 1
}
Risk Monitoring
Get Subaccount Health Factor
Endpoint: GET /subaccounts/health_factor
Monitor the health factor of a subaccount for real-time risk assessment and liquidation prevention.
Authentication Required
โ Yes - API Key Header required
Parameters
address
(required): The subaccount address to check health factor for
Response
Returns health factor data including:
Current health factor value
Total collateral value
Total loan value
Timestamp of calculation
Unique calculation ID
Health Factor Interpretation
> 1.5: Healthy position with low liquidation risk
1.2 - 1.5: Moderate risk, monitor closely
1.0 - 1.2: High risk, consider reducing leverage
< 1.0: Critical risk, liquidation possible
Use Cases
Real-time risk monitoring dashboards
Automated alerting systems
Liquidation prevention tools
Risk management interfaces
Portfolio health checks
Successful Response
Validation Error
GET /api/v1/subaccounts/health_factor?address=text HTTP/1.1
Host:
x-api-key: YOUR_API_KEY
Accept: */*
{
"id": "text",
"datetime": "2025-08-09T00:58:13.765Z",
"health_factor": 1,
"total_collateral_value": 1,
"total_loan_value": 1
}
Trading Operations
Execute Swap
Endpoint: POST /subaccounts/{address}/swaps
Execute token swaps on behalf of a subaccount using the integrated swap aggregation system.
Authentication Required
โ Yes - API Key Header required
Parameters
address
(required): The subaccount address to execute the swap for
Request Body
Requires a SwapQuoteRequest
object containing:
source_token
: Token address to swap fromsource_chain
: Source blockchain networkdestination_token
: Token address to swap todestination_chain
: Destination blockchain networksource_amount
(optional): Amount of source token to swapdestination_amount
(optional): Amount of destination token desiredmarkets
(optional): List of specific markets to use for quotesmax_slippage
(optional): Maximum acceptable slippage in basis points (default: 10)
Response
Returns swap execution details including:
Transaction hash
Source and destination token information
Actual amounts swapped
Fee information
Market used for execution
Use Cases
Portfolio rebalancing
Automated trading strategies
Cross-chain asset transfers
Liquidity management
Arbitrage operations
List of markets to request quotes for. Default is the empty list which returns all.
[]
Maximum slippage allowed (in bips) for the quote. Default slippage is 10 bips.
10
Successful Response
Validation Error
POST /api/v1/subaccounts/{address}/swaps HTTP/1.1
Host:
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 167
{
"source_token": "text",
"source_chain": 1,
"destination_token": "text",
"destination_chain": 1,
"source_amount": 1,
"destination_amount": 1,
"markets": [
"text"
],
"max_slippage": 10
}
{
"transaction_hash": "text",
"source_token": "text",
"destination_token": "text",
"source_chain": 1,
"destination_chain": 1,
"source_amount_in": 1,
"destination_amount_out": 1,
"fee_amount": 0,
"subaccount_id": "123e4567-e89b-12d3-a456-426614174000",
"swapmarket_id": "123e4567-e89b-12d3-a456-426614174000",
"swap_request_id": "123e4567-e89b-12d3-a456-426614174000"
}
Last updated