PUBLIC READ API

API reference

The Arcc Systems HTTP API is read-only. It exposes market state, account positions and protocol parameters for dashboards, analytics, integrations and monitoring. Transactions are always sent from a wallet directly to the contracts.

RESTJSONOpenAPI 3.1Version v1

Quickstart

Base URL: https://arcc.systems/api. Every value reflects live onchain state on Arc Testnet (chain 5042002). Amounts are decimal strings in token units, rates and ratios are decimal fractions (0.0363 = 3.63%).

curl -s https://arcc.systems/api/v1/market | jq
curl -s https://arcc.systems/api/v1/account/0xYourAddress | jq

OpenAPI YAML OpenAPI JSON

Limits, CORS and caching

Rate limit	180 requests per minute per client IP. Above that the API returns `429` with `retry-after: 60`.
CORS	Browser calls are accepted only from `https://arcc.systems`. Call the API from your backend, where CORS does not apply.
Market cache	`/v1/market` is a shared snapshot refreshed at most every 10 seconds.
Parameters cache	`/v1/params` is refreshed at most every 60 seconds.
Delayed data	If the Arc RPC is throttling, `/v1/market` and `/v1/params` return the last good snapshot with `"stale": true`. `asOf` always gives the snapshot time.
Request IDs	Every response carries an `x-request-id` header and a `requestId` field. Include it when reporting a problem.

GET/health

Service health and Arc connectivity. Never cached.

ok	`true` when the API can reach Arc and the chain ID is 5042002. HTTP 200; otherwise 502.
chainId, pool, releaseVersion	Network, Pool address and deployed release.
rpc	Requests per RPC endpoint since the service started: `ok`, `limited` (throttled, moved to the next endpoint) and `fail`. Host names only; no URLs or keys.

GET/v1/meta

API version, release version, chain and Pool address.

{ "apiVersion": "v1", "releaseVersion": "0.5.0", "chain": { "name": "Arc Testnet", "chainId": 5042002 }, "pool": "0xcca1…aC06" }

GET/v1/assets

Assets known to the protocol, with address, decimals and role (supply-borrow or collateral).

GET/v1/market

Pool-wide market state.

totalAssetsUsdc	USDC supplied plus interest owed by borrowers, net of protocol reserves.
totalBorrowsUsdc	Outstanding debt including accrued interest.
availableLiquidityUsdc	USDC that can be withdrawn or borrowed right now.
utilization	Borrowed / supplied, e.g. `0.72` = 72%.
supplyApr / borrowApr	Current variable annual rates, simple (not compounded).
borrowCapUsdc	Pool-wide limit on total borrows.
protocolReservesUsdc	Interest set aside for the protocol (reserve factor).
cumulativeBadDebtWrittenOffUsdc	Total debt ever written off from accounts with no collateral left.
cumulativeReservesUsedForBadDebtUsdc	Part of that written-off debt covered by reserves; the rest reduced supplier balances.
paused	New-risk actions (supply, collateral changes, borrow) are paused.
liquidationsPaused	Liquidation emergency mode is active.
stale, asOf	Snapshot freshness; see caching.

GET/v1/account/:address

One account's position, plus lifetime totals from onchain events. Never cached.

supplyUsdc	Current supplied balance including earned interest.
debtUsdc	Current debt including accrued interest; the amount needed to repay in full now.
healthFactor	Below 1 the position can be liquidated. `"infinity"` when there is no debt.
maxBorrowUsd	Borrow power: collateral value × LTV.
collateral	Deposited collateral per asset.
ledger	Lifetime totals supplied, withdrawn, borrowed and repaid, and interest earned and paid (`interestEarned = supply + withdrawn − supplied`). `null` if the event scan is temporarily unavailable.

{
  "address": "0x78a6557D6ae06CD06f28FEDED8788497aBade9Ca",
  "supplyUsdc": "13.473429",
  "debtUsdc": "94.000383",
  "healthFactor": "174.254609154092489176",
  "maxBorrowUsd": "14700.0",
  "collateral": { "tWETH": "10.5" },
  "ledger": {
    "totalSuppliedUsdc": "14.473398",
    "totalWithdrawnUsdc": "0.999999",
    "totalBorrowedUsdc": "94.5",
    "totalRepaidUsdc": "0.5",
    "interestEarnedUsdc": "0.00003",
    "interestPaidUsdc": "0.000383",
    "basis": "lifetime, from onchain Supplied/Withdrawn/Borrowed/Repaid/Liquidated events",
    "lastBlock": 62787704
  },
  "requestId": "…"
}

GET/v1/params

Protocol parameters and addresses read live from chain. The docs use this endpoint.

contracts	Pool, Oracle, current rate model, Timelock, USDC and tWETH addresses.
roles	Current admin, guardian and treasury.
market	`borrowCapUsdc`, `reserveFactor`, `closeFactor`.
rateModel	`baseRate`, `optimalUtilization` (kink), `slope1`, `slope2`.
collateral[]	Per asset: `ltv`, `liquidationThreshold`, `liquidationBonus`, `supplyCap`, `totalDeposited`, `priceUsd` (`null` if the feed is stale) and `priceMaxAgeSeconds`.
websiteLimits	Limits applied by the arcc.systems interface only, not by the contract.

GET/v1/status

Operational status: price feed freshness, current admins and the liquidation monitor. Never cached.

feeds[]	Per asset: `price`, `updatedAt`, `maxAge`, `stale`, `valid`. Borrowing reverts while a feed is stale.
poolAdmin, oracleAdmin, timelock	Current admin addresses and the Timelock.
monitor	Read-only liquidation monitor: last scanned block and every account with debt, its health factor and whether it is `liquidatable`. It never sends transactions.
block, checkedAt	Chain head and time of this check.

Errors

{
  "error": "human-readable message",
  "code": "MACHINE_CODE",
  "requestId": "…"
}

400 INVALID_ADDRESS	The address is not a valid EVM address.
404 NOT_FOUND	Unknown path.
429 RATE_LIMITED	More than 180 requests in a minute from your IP. Wait for `retry-after` seconds.
502 UPSTREAM_ERROR	Every Arc RPC endpoint failed. Retry after a few seconds.
503 POOL_NOT_CONFIGURED	The API has no Pool address configured.

Try the API

Choose an endpoint to send a live request.