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
Responses
200

Successful Response

application/json
get
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
Query parameters
addressstringRequired
Responses
200

Successful Response

application/json
get
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-29T13:57:49.629Z"
          },
          "apr": 1,
          "initial_principal_amount": 1,
          "deployed_date": "2025-08-29T13:57:49.629Z",
          "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
Query parameters
addressstringRequired
Responses
200

Successful Response

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

{
  "id": "text",
  "datetime": "2025-08-29T13:57:49.629Z",
  "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
Path parameters
addressstringRequired
Body
source_tokenstringRequired
source_chaininteger · enumRequiredPossible values:
destination_tokenstringRequired
destination_chaininteger · enumRequiredPossible values:
source_amountany ofOptional
numberOptional
or
nullOptional
destination_amountany ofOptional
numberOptional
or
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
post
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"
}
PreviousVaultsNextJavascript SDK

Last updated