← Docs

API Reference

Treasury API

The Stackit.ai REST API lets you programmatically manage treasury operations. All endpoints enforce the same safety rails as the dashboard.

Authentication

Stackit.ai supports two authentication methods. Use whichever fits your agent architecture.

Path 1: Bearer Token (treasury-managed agents)

Authorization: Bearer sk_live_your_api_key

API keys are issued during onboarding. Contact support@stackit.ai or book a Treasury Design Call to get started.

Path 2: x402 Micropayment (wallet-sovereign agents)

X-Payment: <base64-encoded payment proof>

No API key signup required. Agents pay per request via HTTP 402 — fully autonomous, no human in the loop.

Base URL

https://api.stackit.ai

Endpoints

Endpoints marked with a 2% fee are subject to volume discounts applied automatically as platform volume grows.

POST/api/v1/depositsFee: 2%

Create Deposit

Initiates a new USDC deposit into the treasury. The system converts deposited funds into BTC and ETH following the user's configured allocation rules.

Parameters

amountnumberrequiredAmount in USDC to deposit. Minimum 100.
allocationobjectBTC/ETH split. Defaults to {"btc": 50, "eth": 50}.

Response

{
  "deposit_id": "dep_abc123",
  "amount_usdc": 10000,
  "fee_usdc": 200,
  "net_amount": 9800,
  "allocation": { "btc": 50, "eth": 50 },
  "status": "processing",
  "created_at": "2026-02-28T12:00:00Z"
}
POST/api/v1/borrowFee: 2% + Aave rate

Create Borrow

Borrow against existing BTC and ETH holdings. The system enforces LTV limits and will reject requests that would breach the safe range. A one-time 2% Stackit.ai fee applies, plus Aave’s variable interest rate on the loan (set by Aave, not Stackit.ai).

Parameters

amountnumberrequiredAmount in USDC to borrow.
purposestringOptional label for the borrow (e.g., 'payroll', 'expenses').

Response

{
  "borrow_id": "brw_def456",
  "amount_usdc": 5000,
  "fee_usdc": 100,
  "current_ltv": 42.5,
  "ltv_after": 45.2,
  "status": "approved",
  "created_at": "2026-02-28T12:00:00Z"
}
POST/api/v1/convertFee: 2%

Convert USDC

Convert USDC holdings into BTC or ETH. Used for dollar-cost averaging and treasury rebalancing.

Parameters

amountnumberrequiredAmount in USDC to convert.
targetstringrequired"btc" or "eth".

Response

{
  "conversion_id": "cnv_ghi789",
  "amount_usdc": 5000,
  "fee_usdc": 100,
  "target": "btc",
  "estimated_amount": 0.052,
  "status": "processing",
  "created_at": "2026-02-28T12:00:00Z"
}
GET/api/v1/treasury

Get Treasury Status

Returns the current state of the treasury including holdings, LTV, health score, and utilization.

Response

{
  "treasury_id": "trs_jkl012",
  "holdings": {
    "btc": 1.25,
    "eth": 15.8,
    "usdc": 2500
  },
  "total_value_usd": 142500,
  "borrowed_usd": 52000,
  "ltv": 36.5,
  "health_score": 87,
  "utilization_score": 64,
  "auto_repay_active": false
}
GET/api/v1/health

Get Health Score

Returns the current health score and LTV breakdown. Use this for monitoring and alerts.

Response

{
  "health_score": 87,
  "ltv": 36.5,
  "ltv_zone": "active",
  "auto_repay_active": false,
  "ltv_zones": {
    "safe": { "min": 0, "max": 35 },
    "active": { "min": 35, "max": 50 },
    "ceiling": { "min": 50, "max": 60 },
    "hard_ceiling": 60
  }
}
POST/api/v1/repay

Manual Repay

Manually repay a portion of the outstanding borrow. Reduces LTV and increases borrowing capacity.

Parameters

amountnumberrequiredAmount in USDC to repay.

Response

{
  "repayment_id": "rep_mno345",
  "amount_usdc": 2000,
  "ltv_before": 45.2,
  "ltv_after": 41.8,
  "remaining_borrow": 50000,
  "status": "completed"
}
POST/api/v1/estimate

Estimate Fees

Estimate fees and net amounts for a treasury action before executing it. Returns the Stackit.ai fee, Aave rate (for borrows), DEX spread (for conversions), and net amount. No fee to call this endpoint.

Parameters

actionstringrequired"deposit", "borrow", "convert", or "repay".
amountnumberrequiredAmount in USDC.
targetstring"btc" or "eth" (required for convert action).

Response

{
  "action": "deposit",
  "amount_usdc": 10000,
  "stackit_fee": 200,
  "aave_rate": null,
  "dex_spread": null,
  "net_amount": 9800,
  "estimated_at": "2026-02-28T12:00:00Z"
}

Error Codes

400

Bad Request

Missing or invalid parameters.

401

Unauthorized

Invalid or missing API key.

403

LTV Limit Exceeded

The requested action would breach the configured LTV ceiling (default 60%, adjustable based on lending protocol limits).

404

Not Found

The requested resource does not exist.

409

Conflict

A conflicting operation is in progress (e.g., pending deposit).

429

Rate Limited

Too many requests. Retry after the indicated delay.

500

Server Error

Internal error. Contact support@stackit.ai.

All error responses return a consistent JSON body:

{
  "error": "ltv_limit_exceeded",
  "message": "Borrow would push LTV to 67.3%, exceeding the 60% ceiling",
  "safe_amount": 4200,
  "current_ltv": 42.5,
  "request_id": "req_abc123"
}

Every error includes an error code (machine-readable), a human-readable message, and contextual fields like safe_amount so agents can retry with adjusted parameters.

Rate Limits

Read endpoints (GET)

100 requests per minute

Write endpoints (POST)

20 requests per minute

Rate limit headers are included in every response: X-RateLimit-Remaining and X-RateLimit-Reset.

Ready to integrate?

Book a Treasury Design Call to get your API keys and start building.