← 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.

Machine-readable spec: /openapi.json

Your first call in 10 seconds

Public evaluation endpoints require no signup and no API key. They let agents verify market data, liquidation math, demo portfolio state, gateway status, and typed preview errors before live access.

curl -s https://www.stackit.ai/api/v1/public/liquidation-distance?ltv=40 | jq
https://www.stackit.ai/api/v1/public/market-rateshttps://www.stackit.ai/api/v1/public/portfolio-state?address=demohttps://www.stackit.ai/api/v1/public/gateway-statushttps://www.stackit.ai/api/v1/public/policy-state?address=demohttps://www.stackit.ai/api/v1/public/preview

Full runnable ladder: /docs/quickstart-agents

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

Idempotency-Key: unique-action-id-001

API keys are issued during onboarding. Agents can apply programmatically via POST /api/v1/agents/apply (or the request_live_access MCP tool); humans can contact support@stackit.ai or book a Treasury Design Call. Managed treasuries run on an operator-owned wallet where Stackit.ai automation is a revocable additional signer gated by an on-wallet, deny-all-by-default policy — delegation state is readable via get_policy_state. State-changing action calls also require a unique Idempotency-Key header to prevent replay.

Path 2: x402 Micropayment (wallet-sovereign agents)

X-Payment: <base64-encoded payment proof>

Idempotency-Key: unique-action-id-001

No API key signup required. Agents pay per request via HTTP 402. Status: live on Base Sepolia (testnet), x402 protocol v1. Priced endpoints return spec-correct 402 challenges and settle testnet USDC through the public facilitator; mainnet settlement on Base activates with the Base deployment. See /docs/x402 and /x402/prices.json.

Base URL

https://www.stackit.ai/api/v1

All public, sandbox, and MCP endpoints are served from this host today. Public no-auth path: https://www.stackit.ai/api/v1/public. A dedicated production host (api.stackit.ai) launches alongside Base support; until then it does not resolve.

Endpoints

Fees: 2% on deposits, 2% of the amount converted, and 2% per borrowing execution — including automated re-leverage cycles. Downward legs, repayment, and exits are always free, and every fee-bearing execution is itemized with its trigger. State-changing action routes require an Idempotency-Key header.

POST/api/v1/deposits

Create Deposit

Initiates a new USDC deposit into the treasury. Deposits carry the 2% entry fee; converting USDC into BTC or ETH carries the separate 2% buy fee.

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,
  "status": "processing",
  "created_at": "2026-02-28T12:00:00Z"
}
POST/api/v1/borrowFee: 2% per execution + Aave rate

Create Borrow

Borrow against existing BTC and ETH holdings. Stackit.ai charges 2% of the amount borrowed, per execution — manual borrows and automated re-leverage cycles alike; downward legs are always free. Aave variable interest still applies.

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,
  "fee_basis": "2% of the amount borrowed, per execution",
  "current_ltv": 42.5,
  "ltv_after": 45.2,
  "status": "approved",
  "created_at": "2026-02-28T12:00:00Z"
}
POST/api/v1/convertFee: 2%

Buy BTC or ETH

Convert USDC holdings into BTC or ETH. Stackit.ai charges 2% of the amount converted.

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 before executing, including previewed automated re-leverage cycles. Returns 2% of the amount for deposits, conversions, and borrowing executions; $0 for every downward leg and exit.

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,
  "fee_basis": "2% when funds enter Stackit",
  "aave_rate": null,
  "dex_spread": null,
  "net_amount": 10000,
  "estimated_at": "2026-02-28T12:00:00Z"
}
POST/api/v1/treasuries

Create Treasury

Register a simulated treasury bound to your wallet. Returns a treasury_id and an api_key for action calls. With execution_mode 'wallet' (default), actions return unsigned transactions for your wallet to sign — Stackit.ai never holds private keys. GET this endpoint for the full input schema and preset definitions.

Parameters

wallet_addressstringrequired0x-prefixed wallet address the treasury operates from.
chainstring"arbitrum" or "base". Defaults to "base".
presetstring"conservative", "balanced", or "aggressive" — controls LTV bands and the borrow ceiling. Defaults to "balanced".
execution_modestring"wallet" (unsigned-tx loop, default) or "managed" (immediate simulated execution).

Response

{
  "sandbox": true,
  "object": "treasury",
  "treasury_id": "trs_1a2b3c4d5e6f7a8b",
  "api_key": "sk_test_...",
  "wallet_address": "0xYourWallet...",
  "chain": "base",
  "preset": "balanced",
  "policy": { "live_band": { "min": 35, "max": 50 }, "ceiling": 60, "park_target": 25 },
  "execution_mode": "wallet",
  "status": "active"
}
GET/api/v1/treasuries/{id}

Get Treasury

Fetch a treasury's configuration, policy preset, and current simulated state by treasury_id.

Response

{
  "sandbox": true,
  "object": "treasury",
  "treasury_id": "trs_1a2b3c4d5e6f7a8b",
  "wallet_address": "0xYourWallet...",
  "preset": "balanced",
  "execution_mode": "wallet",
  "state": { "usdc_balance": 10000, "ltv": 0, "health_score": 92 }
}
POST/api/v1/relay

Relay Signed Transaction

Complete the wallet-sovereign loop: submit the signed transaction for a pending unsigned envelope. Execution is simulated today; real broadcasting activates with the Base deployment. Unsigned envelopes expire after 15 minutes.

Parameters

tx_idstringrequiredThe tx_ id from the unsigned_transaction envelope.
signed_transactionstringrequired0x-prefixed hex of the wallet-signed transaction.

Response

{
  "sandbox": true,
  "object": "relay_receipt",
  "tx_id": "tx_9f8e7d6c5b4a3210",
  "tx_hash": "0x...",
  "simulated": true,
  "chain": "base",
  "status": "confirmed",
  "result": { "action": "borrow", "amount_usdc": 3000, "resulting_ltv": 41.6 }
}
POST/api/v1/agents/apply

Request Live Access (Agents)

Submit a live-access request programmatically. A human reviews every request and contacts the operator email with the outcome and credentials, typically within 2 business days. GET this endpoint without a body to retrieve the full input schema.

Parameters

operator_namestringrequiredHuman operator responsible for the agent.
operator_emailstringrequiredEmail where the operator receives the review outcome and credentials.
use_casestringrequiredWhat the treasury is for: accumulation cadence, borrow needs, autonomy level.
agent_namestringName or identifier of the agent applying.
agent_frameworkstringe.g. claude-agent-sdk, langchain, custom.
wallet_addressstringWallet the treasury will operate from (self-custody by default).
chainstring"arbitrum" (live today) or "base" (agent support in development).

Response

{
  "object": "agent_access_request",
  "id": "agr_1a2b3c4d5e6f7a8b",
  "status": "received",
  "status_url": "https://www.stackit.ai/api/v1/agents/apply/agr_1a2b3c4d5e6f7a8b",
  "review_process": "A human reviews every agent access request...",
  "docs": "https://www.stackit.ai/docs/quickstart-agents"
}
GET/api/v1/agents/apply/{id}

Get Access Request Status

Poll the review status of a live-access request. Status moves from received to in_review to closed as a human processes it.

Response

{
  "object": "agent_access_request",
  "id": "agr_1a2b3c4d5e6f7a8b",
  "status": "in_review",
  "submitted_at": "2026-06-12T12:00:00Z",
  "status_meaning": {
    "received": "Queued for human review.",
    "in_review": "A human has picked up the request and is contacting the operator.",
    "closed": "Review complete. The operator was contacted with the outcome."
  }
}
GET/api/v1/public/policy-state

Get Demo Policy State

Returns policy-state fields agents need to diff against an operator mandate: protection status, dormancy clock, monitoring tier, gas caps, and fee schedule reference.

Response

{
  "protection_status": "active",
  "monitoring_tier": { "tier": "active", "check_frequency": "high-frequency" },
  "gas_caps": { "per_action_usd": 0.25, "per_month_usd": 5 },
  "fee_schedule_ref": "https://www.stackit.ai/fees.json"
}

The wallet-sovereign loop

The full self-custody contract is live in simulation: create a treasury with execution_mode: "wallet", and every action returns an unsigned transaction envelope (real Aave V3 pool address, simulated calldata) for your wallet to sign. Submit the signature to POST /api/v1/relay (MCP: relay_signed_transaction) to get a receipt and updated state. Stackit.ai never holds private keys, and unsafe borrows are rejected with typed errors before a signature is ever requested. Use a fresh Idempotency-Key for both the action preview request and the relay request.

Integrate against this contract now — at the Base deployment, the same loop broadcasts real transactions and the simulated calldata becomes real Aave V3 calldata.

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.