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

Get My Subaccounts

get

Authorizations

x-api-keystringRequired

Responses

200

Successful Response

application/json

get

/subaccounts

GET /api/v1/subaccounts HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Accept: */*

200

Successful Response

[
  {
    "address": "text",
    "name": "text",
    "status": "text",
    "chains": [
      {
        "chain_id": 1,
        "name": "text"
      }
    ]
  }
]

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

Get Subaccount Summary

get

Authorizations

x-api-keystringRequired

Query parameters

addressstringRequired

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/subaccounts/summary

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-12-15T21:23:15.006Z"
          },
          "apr": 1,
          "initial_principal_amount": 1,
          "deployed_date": "2025-12-15T21:23:15.006Z",
          "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

Get Subaccount Health Factor

get

Authorizations

x-api-keystringRequired

Query parameters

addressstringRequired

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/subaccounts/health_factor

GET /api/v1/subaccounts/health_factor?address=text HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "datetime": "2025-12-15T21:23:15.006Z",
  "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 from
source_chain: Source blockchain network
destination_token: Token address to swap to
destination_chain: Destination blockchain network
source_amount (optional): Amount of source token to swap
destination_amount (optional): Amount of destination token desired
markets (optional): List of specific markets to use for quotes
max_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

Do Swap

post

Authorizations

x-api-keystringRequired

Path parameters

addressstringRequired

Body

source_tokenstringRequired

source_chaininteger · enumRequiredPossible values:

destination_tokenstringRequired

destination_chaininteger · enumRequiredPossible values:

source_amountany ofOptional

numberOptional

nullOptional

destination_amountany ofOptional

numberOptional

nullOptional

marketsstring[]Optional

List of markets to request quotes for. Default is the empty list which returns all.

Default: []

max_slippagenumberOptional

Maximum slippage allowed (in bips) for the quote. Default slippage is 10 bips.

Default: 10

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/subaccounts/{address}/swaps

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"
}

PreviousVaults NextJavascript SDK

Last updated 4 months ago