AugustApi

The August backend API Module — read-only client for public backend endpoints (transparency dashboard, unrealized PnL) and authenticated loan-book / risk / OTC reads. Accessible as sdk.apiModule.

Read-only client for August backend REST endpoints that have no on-chain equivalent: the unrealized-PnL series, the transparency dashboard (position snapshot, backing series, smoothed APY, allocations, fee config, governance), plus authenticated loan-book / risk / OTC reads.

Every public method makes exactly one HTTPS request to the August API and zero RPC calls. Responses are not cached by the SDK: this is time-sensitive state where staleness is worse than a request. Accessible as sdk.apiModule; only the unrealized-PnL methods are also mirrored on the root AugustSDK class.

Extends: AugustBase

Constructors

Constructor

new AugustApi(baseConfig): AugustApi

Parameters

Returns

AugustApi

Overrides

AugustBase.constructor

Properties

Methods

clearWallet()

clearWallet(): void

Remove wallet address from SDK state and monitoring headers.

Returns

void

Inherited from

AugustBase.clearWallet

getCollateralExcessOrDeficit()

getCollateralExcessOrDeficit(params): Promise<ICollateralExcessOrDeficit>

Compute how much collateral a subaccount has in excess of — or is short of — what it needs to hold a target health factor, for one collateral token.

Backed by GET /risk/collateral_excess_or_deficit (60-second server-side cache), which resolves the subaccount and reads its current health factor, so an authenticated (admin-scoped) August API key is required. Makes exactly one HTTP request and no RPC calls.

Parameters

Returns

Promise<ICollateralExcessOrDeficit>

The signed excess (positive) or deficit (negative) in USD and token units. Zeroes when the subaccount has no debt.

Throws

AugustValidationError When an address is invalid, tokenChain is not an integer, or targetHealthFactor is out of range.

Throws

AugustServerError When the token has no discount factor (backend 404) or the API otherwise responds non-2xx.

Example

const r = await sdk.apiModule.getCollateralExcessOrDeficit({
    subaccount: '0xabc…',
    tokenAddress: '0xdef…',
    tokenChain: 1,
  });
  console.log(r.amount_usd > 0 ? 'excess' : 'deficit');

getCuratorVaultSubaccounts()

getCuratorVaultSubaccounts(vaultAddress): Promise<IWSSubaccountListItem[]>

List the subaccounts linked to a vault (curator surface).

Backed by the curator-or-admin GET /curator/vaults/{vault_address}/subaccounts backend endpoint, so the configured August API key must belong to the vault's curator or an admin. Makes exactly one HTTP request and no RPC calls.

Parameters

Returns

Promise<IWSSubaccountListItem[]>

Array of subaccount records linked to the vault (same shape as the subaccount directory); empty when none are linked.

Throws

AugustValidationError When vaultAddress is not a valid address.

Throws

AugustAuthError When the API key is missing or not curator/admin for the vault.

Throws

AugustServerError When the API responds with a non-2xx status.

Example

const subs = await sdk.apiModule.getCuratorVaultSubaccounts('0xvault…');

getCuratorVaultWhitelist()

getCuratorVaultWhitelist(vaultAddress): Promise<ICuratorWhitelistStatus[]>

Get on-chain whitelist status for every subaccount linked to a vault (curator surface).

Backed by the curator-or-admin GET /curator/vaults/{vault_address}/whitelist backend endpoint. EVM vaults only — non-EVM vaults manage access internally and the backend returns a 400 (surfaced as AugustServerError). Makes exactly one HTTP request and no RPC calls from the SDK.

Parameters

Returns

Promise<ICuratorWhitelistStatus[]>

Array of ICuratorWhitelistStatus, one per linked subaccount; empty when the vault has no subaccounts.

Throws

AugustValidationError When vaultAddress is not a valid address.

Throws

AugustAuthError When the API key is missing or not curator/admin for the vault.

Throws

AugustServerError When the vault is non-EVM (backend 400) or the API otherwise responds non-2xx.

Example

const status = await sdk.apiModule.getCuratorVaultWhitelist('0xvault…');
  console.log(status.filter((s) => !s.is_whitelisted));

getDashboardLoans()

getDashboardLoans(): Promise<ILoanBookInfo[]>

Retrieve the global loan-book aggregate across every active client subaccount — one ILoanBookInfo entry per loan, with principal / interest amounts, APRs, state, and the next upcoming payment.

Backed by the admin-only GET /dashboard/loans backend endpoint (60-second server-side cache), so the August API key configured on the SDK must belong to an admin user. Makes exactly one HTTP request and no RPC calls.

Returns

Promise<ILoanBookInfo[]>

Array of loan-book entries; empty when there are no active loans.

Throws

AugustAuthError When the API key is missing or not admin-scoped.

Throws

AugustServerError When the API responds with a non-2xx status.

Example

const loans = await sdk.apiModule.getDashboardLoans();
  const active = loans.filter((l) => l.state === 'ACTIVE');

getDiscountFactors()

getDiscountFactors(): Promise<IDiscountFactorLadder[]>

Retrieve every token discount-factor ladder the risk engine applies when valuing collateral.

Backed by GET /risk/discount_factors (60-second server-side cache), which requires an authenticated August user; an admin-scoped API key works. Makes exactly one HTTP request and no RPC calls.

Returns

Promise<IDiscountFactorLadder[]>

Array of IDiscountFactorLadder, one per whitelisted token that has a configured ladder.

Throws

AugustAuthError When the API key is missing or not authorized.

Throws

AugustServerError When the API responds with a non-2xx status.

Example

const ladders = await sdk.apiModule.getDiscountFactors();
  console.log(ladders.map((d) => `${d.address}@${d.chain}`));

getLatestUnrealizedPnl()

getLatestUnrealizedPnl(): Promise<IUnrealizedPnlSnapshot[]>

Fetch the latest unrealized-PnL snapshot for every vault the backend tracks — one entry per vault.

Makes one HTTPS request to the public August API; no RPC calls.

Returns

Promise<IUnrealizedPnlSnapshot[]>

Array of IUnrealizedPnlSnapshot, one per tracked vault.

Throws

AugustServerError When the API responds with a 5xx, or returns a body that is not a snapshot array.

Throws

AugustRateLimitError When the API responds 429.

Throws

AugustTimeoutError When the request exceeds the SDK request timeout.

Example

const all = await sdk.getLatestUnrealizedPnl();
  const losing = all.filter((s) => s.unrealizedPnl < 0);

getOtcMarginRequirements()

getOtcMarginRequirements(options): Promise<IOtcMarginRequirement[]>

Retrieve OTC margin requirements, optionally filtered by counterparty and/or payer.

Backed by the admin-only GET /otc/margin_requirement backend endpoint, so the configured August API key must belong to an admin user. Makes exactly one HTTP request and no RPC calls.

Parameters

Returns

Promise<IOtcMarginRequirement[]>

Array of IOtcMarginRequirement matching the filters (all when none given).

Throws

AugustAuthError When the API key is missing or not admin-scoped.

Throws

AugustServerError When the API responds with a non-2xx status.

Example

const reqs = await sdk.apiModule.getOtcMarginRequirements({ payer: '0xabc…' });

getOtcPositions()

getOtcPositions(): Promise<IOtcPositionRead[]>

Retrieve every tracked OTC position.

Backed by the admin-only GET /otc/position backend endpoint, so the configured August API key must belong to an admin user. Makes exactly one HTTP request and no RPC calls.

Returns

Promise<IOtcPositionRead[]>

Array of IOtcPositionRead; empty when there are no OTC positions.

Throws

AugustAuthError When the API key is missing or not admin-scoped.

Throws

AugustServerError When the API responds with a non-2xx status.

Example

const positions = await sdk.apiModule.getOtcPositions();

getRevertReason()

getRevertReason(txHash, chain): Promise<IRevertReason>

Fetch the decoded revert reason(s) for a transaction — error messages, revert strings, and recognized universal-subaccount errors extracted from a debug_traceTransaction call tree.

Backed by the public (unauthenticated) GET /revert_reason endpoint; no API key required. The backend relies on the target chain's RPC supporting debug_trace*; on chains/RPCs without it the backend returns a 5xx whose detail explains why, surfaced here as an AugustServerError. Makes exactly one HTTP request and no RPC calls from the SDK itself.

Parameters

Returns

Promise<IRevertReason>

The decoded IRevertReason; all arrays empty when the trace yielded no matching signal.

Throws

AugustValidationError When txHash is empty or chain is not an integer.

Throws

AugustServerError When the chain/RPC does not support tracing, or the API otherwise responds non-2xx.

Example

const r = await sdk.apiModule.getRevertReason('0xabc…', 1);
  console.log(r.revert_reasons);

getTimelockRequests()

getTimelockRequests(params): Promise<ITimelockRequest[]>

List timelock (governance) requests for a vault on a chain, optionally filtered by status.

Backed by the GET /timelock-requests backend endpoint. Makes exactly one HTTP request and no RPC calls.

Parameters

Returns

Promise<ITimelockRequest[]>

Array of ITimelockRequest; empty when the vault has no matching requests.

Throws

AugustValidationError When vaultAddress is invalid or chainId is not a positive integer.

Throws

AugustServerError When the API responds with a non-2xx status (e.g. an invalid status filter).

Example

const reqs = await sdk.apiModule.getTimelockRequests({ vaultAddress: '0xvault…', chainId: 1 });

getVaultBackingSeries()

getVaultBackingSeries(params): Promise<ITransparencyRatioPoint[]>

Fetch the backing / supply / collateral-ratio time series behind the Performance tab's "Backing vs Supply" and "Collateral Ratio" charts, and the Overview sidebar's 7-day deltas.

Public GET /upshift/unrealized_pnl?fields=ratio; no API key. One HTTPS request, no RPC. Points are hourly, returned newest-first — sort before charting. actual_tvl = backing (mark-to-market), tvl_on_vault = supply (vault-reported), adjusted_redeem_ratio = collateral ratio.

Unlike the chain-scoped transparency endpoints (positions, fees, governance…), this one is keyed by vault address only and accepts non-EVM (Solana / Stellar) vaults — same contract as AugustApi.getVaultUnrealizedPnlHistory, which it shares a route with.

Parameters

Returns

Promise<ITransparencyRatioPoint[]>

Array of ITransparencyRatioPoint; empty when no history.

Throws

AugustValidationError When arguments fail validation (no request is made).

Throws

AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).

Throws

AugustServerError (status 200) When the body is not the documented shape — backend contract drift.

Throws

AugustRateLimitError When the API responds 429.

Throws

AugustTimeoutError When the request exceeds the SDK request timeout.

Example

const pts = await sdk.apiModule.getVaultBackingSeries({ vault, startDate: '2026-08-01' });
const ratio = pts.map((p) => p.adjusted_redeem_ratio * 100); // percent

getVaultFeeConfig()

getVaultFeeConfig(params): Promise<ITransparencyFees>

Fetch a vault's fee configuration — the Performance tab's fee card.

Public GET /upshift/fees/{vault_address}; no API key. One HTTPS request, no RPC. Percent fields are already scaled (management_fee_pct of 1.5 means 1.5%).

Parameters

Returns

Promise<ITransparencyFees>

ITransparencyFees.

Throws

AugustValidationError When arguments fail validation (no request is made).

Throws

AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).

Throws

AugustServerError (status 200) When the body is not the documented shape — backend contract drift.

Throws

AugustRateLimitError When the API responds 429.

Throws

AugustTimeoutError When the request exceeds the SDK request timeout.

Example

const fees = await sdk.apiModule.getVaultFeeConfig({ vault, chainId: 143 });
console.log(`${fees.management_fee_pct}% mgmt / ${fees.performance_fee_pct}% perf`);

getVaultGovernanceAuditLog()

getVaultGovernanceAuditLog(params): Promise<ITransparencyAuditLog>

Fetch one page of the vault's governance audit log, newest first — the Governance tab's "Audit Log" timeline. Merges live timelock events with manually recorded entries (attestations, permission changes).

Public GET /upshift/governance/{vault_address}/audit_log; no API key. Paginate with before = the last returned entry's timestamp while has_more is true (exclusive cursor; ties at the exact boundary timestamp are skipped, never duplicated).

Parameters

Returns

Promise<ITransparencyAuditLog>

ITransparencyAuditLog.

Throws

AugustValidationError When arguments fail validation (no request is made).

Throws

AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).

Throws

AugustServerError (status 200) When the body is not the documented shape — backend contract drift.

Throws

AugustRateLimitError When the API responds 429.

Throws

AugustTimeoutError When the request exceeds the SDK request timeout.

Example

// Walk the whole log, newest first.
let before: string | undefined;
do {
  const page = await sdk.apiModule.getVaultGovernanceAuditLog({ vault, chainId: 1, before, limit: 50 });
  for (const e of page.entries) console.log(e.timestamp, e.type, e.summary);
  before = page.has_more ? page.entries.at(-1)?.timestamp : undefined;
} while (before);

getVaultGovernancePermissions()

getVaultGovernancePermissions(params): Promise<ITransparencyGovernancePermissions>

Fetch the integrations each vault wallet is whitelisted to operate — the Governance tab's "Vault Permissions" table.

Public GET /upshift/governance/{vault_address}/permissions; no API key. One HTTPS request, no RPC.

Parameters

Returns

Promise<ITransparencyGovernancePermissions>

ITransparencyGovernancePermissions.

Throws

AugustValidationError When arguments fail validation (no request is made).

Throws

AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).

Throws

AugustServerError (status 200) When the body is not the documented shape — backend contract drift.

Throws

AugustRateLimitError When the API responds 429.

Throws

AugustTimeoutError When the request exceeds the SDK request timeout.

Example

const { permissions } = await sdk.apiModule.getVaultGovernancePermissions({ vault, chainId: 143 });
for (const p of permissions) console.log(p.integration, p.functions.join(','));

getVaultGovernanceRoles()

getVaultGovernanceRoles(params): Promise<ITransparencyGovernanceRoles>

Fetch the vault's privileged addresses (owner / operators) with custody enrichment — the Governance tab's "Vault Roles" card.

Public GET /upshift/governance/{vault_address}/roles; no API key. One HTTPS request from the SDK (the backend performs the on-chain reads). Third-party enrichment failures (Safe / Fordefi) degrade rows and append to warnings rather than failing.

Parameters

Returns

Promise<ITransparencyGovernanceRoles>

ITransparencyGovernanceRoles.

Throws

AugustValidationError When arguments fail validation (no request is made).

Throws

AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).

Throws

AugustServerError (status 200) When the body is not the documented shape — backend contract drift.

Throws

AugustRateLimitError When the API responds 429.

Throws

AugustTimeoutError When the request exceeds the SDK request timeout.

Example

const { roles, warnings } = await sdk.apiModule.getVaultGovernanceRoles({ vault, chainId: 143 });
const owner = roles.find((r) => r.role === 'owner'); // owner?.is_safe → Safe threshold in safe_threshold

getVaultGovernanceTimelocks()

getVaultGovernanceTimelocks(params): Promise<ITransparencyTimelocks>

Fetch the vault's timelock queue — the Governance tab's "Pending Timelocks" table. Defaults to pending (scheduled) requests.

Public GET /upshift/governance/{vault_address}/timelocks; no API key. executable_at is scheduled_at + TIMELOCK_DURATION() read live from the timelock contract; null (plus a warning) when that read failed. The default filter is pending only — the list is often empty; pass status: 'all' for history. getTimelockRequests returns the raw backend rows; this returns the dashboard view (labels, executable_at, warnings).

Parameters

Returns

Promise<ITransparencyTimelocks>

ITransparencyTimelocks.

Throws

AugustValidationError When arguments fail validation (no request is made).

Throws

AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).

Throws

AugustServerError (status 200) When the body is not the documented shape — backend contract drift.

Throws

AugustRateLimitError When the API responds 429.

Throws

AugustTimeoutError When the request exceeds the SDK request timeout.

Example

const { timelocks } = await sdk.apiModule.getVaultGovernanceTimelocks({ vault, chainId: 1 }); // pending only
const ready = timelocks.filter((t) => t.executable_at && Date.parse(`${t.executable_at}Z`) <= Date.now());

getVaultHistoricalAllocations()

getVaultHistoricalAllocations(params): Promise<ITransparencyHistoricalAllocations>

Fetch daily allocation history per protocol — the Performance tab's "Allocation Over Time" chart.

Public GET /upshift/historical_allocations/{vault_address}; no API key. One HTTPS request, no RPC.

Parameters

Returns

Promise<ITransparencyHistoricalAllocations>

ITransparencyHistoricalAllocations.

Throws

AugustValidationError When arguments fail validation (no request is made).

Throws

AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).

Throws

AugustServerError (status 200) When the body is not the documented shape — backend contract drift.

Throws

AugustRateLimitError When the API responds 429.

Throws

AugustTimeoutError When the request exceeds the SDK request timeout.

Example

const h = await sdk.apiModule.getVaultHistoricalAllocations({ vault, chainId: 143, startDate: '2026-08-01' });
const byDate = Map.groupBy(h.points, (p) => p.date);

getVaultOracleClassification()

getVaultOracleClassification(vault, chainId): Promise<IOracleClassification>

Fetch a vault's NAV-oracle classification table — how each position/token is priced (Primary / Secondary Market / CeFi) and its USD value, plus warnings for tokens that could not be resolved.

Backed by the public (unauthenticated) GET /upshift/oracle_classification/{vault_address} endpoint; no API key required. Reads the newest daily snapshot. Makes exactly one HTTP request and no RPC calls from the SDK.

Parameters

Returns

Promise<IOracleClassification>

The vault's IOracleClassification.

Throws

AugustValidationError When vault is invalid or chainId is not an integer.

Throws

AugustServerError When the vault or its snapshot is not found, or the API otherwise responds non-2xx.

Example

const cls = await sdk.apiModule.getVaultOracleClassification('0xvault…', 1);
  console.log(cls.warnings);

getVaultPerformanceFees()

getVaultPerformanceFees(params): Promise<IVaultPerformanceFees>

Compute a vault's performance fees over a period (backend-computed from its snapshot history).

Backed by GET /metrics/vault_performance_fees. The backend runs pandas over the vault's full snapshot history, so the first call is slow; results are cached server-side for 20 minutes. Makes exactly one HTTP request and no RPC calls.

Parameters

Returns

Promise<IVaultPerformanceFees>

The vault's IVaultPerformanceFees computation.

Throws

AugustValidationError When vault is invalid, or exactly one of startDate/endDate is supplied.

Throws

AugustServerError When there is insufficient snapshot data for the period, or the API otherwise responds non-2xx.

Example

const fees = await sdk.apiModule.getVaultPerformanceFees({ vault: '0xvault…' });
  console.log(fees.total_perf_fees_asset);

getVaultPositionSnapshot()

getVaultPositionSnapshot(params): Promise<ITransparencyPositions>

Fetch the latest position snapshot for a vault, grouped per wallet — the data behind the transparency Overview tab (strategy breakdown, backing composition, vault buffer, per-wallet table, headline TVL).

Public GET /upshift/positions/{vault_address}; no API key. One HTTPS request, no RPC. Snapshots land hourly; every field is from the single snapshot_at instant. Vault buffer = total_nav − Σ subaccounts[].total_usd; reported_tvl is the vault-contract-reported total assets from the same snapshot.

Parameters

Returns

Promise<ITransparencyPositions>

ITransparencyPositions.

Throws

AugustValidationError When arguments fail validation (no request is made).

Throws

AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).

Throws

AugustServerError (status 200) When the body is not the documented shape — backend contract drift.

Throws

AugustRateLimitError When the API responds 429.

Throws

AugustTimeoutError When the request exceeds the SDK request timeout.

Example

const p = await sdk.apiModule.getVaultPositionSnapshot({ vault: '0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA', chainId: 143 });
const buffer = p.total_nav - p.subaccounts.reduce((a, s) => a + s.total_usd, 0);

getVaultSmoothedApy()

getVaultSmoothedApy(params): Promise<ITransparencyApySeries>

Fetch the smoothed 7-day APY series — the exact series the Upshift app charts (Overview "APY last 30 days" and Performance "APY Over Time").

Public GET /upshift/historical_apy/chart; no API key. One HTTPS request, no RPC. The backend marks this route deprecated in its OpenAPI spec but it remains the series the Upshift app itself charts; this wrapper tracks it. The backend applies a rolling-median/mean smoothing filter server-side when applySmoothing is true (the app default); computing APY locally from raw share ratios will NOT match the published figures.

Unlike the chain-scoped transparency endpoints (positions, fees, governance…), this one is keyed by vault address only and accepts non-EVM (Solana / Stellar) vaults.

Parameters

Returns

Promise<ITransparencyApySeries>

ITransparencyApySeries — labels are M/D/YYYY, values are decimal fractions (0.0245 = 2.45%). Empty arrays when the vault has no data.

Throws

AugustValidationError When arguments fail validation (no request is made).

Throws

AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).

Throws

AugustServerError (status 200) When the body is not the documented shape — backend contract drift.

Throws

AugustRateLimitError When the API responds 429.

Throws

AugustTimeoutError When the request exceeds the SDK request timeout.

Example

const apy = await sdk.apiModule.getVaultSmoothedApy({ vault, daysAgo: 30 });
console.log(apy.values.at(-1)); // latest 7D APY as a fraction

getVaultUnrealizedPnlHistory()

getVaultUnrealizedPnlHistory(params): Promise<IUnrealizedPnlSnapshot[]>

Fetch the historical unrealized-PnL series for a vault, newest first, as computed by the August backend from periodic vault snapshots.

Makes one HTTPS request to the public August API; no RPC calls.

Parameters

Returns

Promise<IUnrealizedPnlSnapshot[]>

Array of IUnrealizedPnlSnapshot; empty when the backend has no history for the vault.

Throws

AugustValidationError When vault is not a valid address or limit is out of range.

Throws

AugustServerError When the API responds with a 5xx, or returns a body that is not a snapshot array.

Throws

AugustRateLimitError When the API responds 429.

Throws

AugustTimeoutError When the request exceeds the SDK request timeout.

Example

const series = await sdk.getVaultUnrealizedPnlHistory({ vault: '0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA', limit: 30 });
  console.log(series[0]?.unrealizedPnlInAsset);

init()

init(): Promise<void>

Verify the configured August API key and mark this instance as authorized.

Returns

Promise<void>

Throws

Error when keys.august is missing or rejected by the API.

Inherited from

AugustBase.init

simulateCollateral()

simulateCollateral(input): Promise<ICollateralSimulationResults>

Simulate the collateral required to open a hypothetical loan against a chosen basket of collateral tokens.

This is a pure, read-only simulation: the backend POST /risk/collateral_simulation endpoint (60-second server-side cache) computes required collateral and effective discount factors and changes no state. It runs against the authenticated backend, so an (admin-scoped) August API key is required. Makes exactly one HTTP request and no RPC calls.

Parameters

Returns

Promise<ICollateralSimulationResults>

The simulated ICollateralSimulationResults: total debt, required collateral, resulting health factor, and a per-token breakdown.

Throws

AugustValidationError When addresses are invalid, loan_amount is not a finite non-negative number, the collateral arrays are empty / mismatched, or on_platform is set without redeployed-token details.

Throws

AugustServerError When the API responds with a non-2xx status (e.g. a token missing a discount factor).

Example

const sim = await sdk.apiModule.simulateCollateral({
    loan_token_chain: 1,
    loan_token_address: '0xloan…',
    loan_amount: 1_000_000,
    collateral_tokens: [[1, '0xcol…']],
    collateral_token_allocation: [1],
  });
  console.log(sim.total_required_collateral_usd);

switchNetwork()

switchNetwork(chainId): void

Switch the active blockchain network. Updates both chain ID and RPC URL for subsequent operations.

Parameters

Returns

void

Inherited from

AugustBase.switchNetwork

updateWallet()

updateWallet(address): void

Set active wallet address and update monitoring headers. Preserves existing environment setting.

Parameters

Returns

void

Inherited from

AugustBase.updateWallet