Skip to main content
Version: 1.0.0

1delta API v1

Unified API for DeFi data and actions.

Machine-readable spec​

ArtefactURL
OpenAPI 3.1 (enriched, what this site renders)https://docs.1delta.io/openapi.json
OpenAPI 3.1 (raw, from the API server)https://portal.1delta.io/v1/openapi.json
Endpoint index for LLMshttps://docs.1delta.io/llms.txt
Full flattened reference for LLMshttps://docs.1delta.io/llms-full.txt

If you are pointing a coding agent at this API, give it llms-full.txt — it carries every endpoint, parameter, field and example as plain text, with no JavaScript required.

Authentication & rate limits​

Every endpoint is public. Send an API key as the x-api-key header to raise your rate limit; get one at auth.1delta.io. Unauthenticated traffic is limited per IP — treat 429 as retryable with exponential backoff rather than assuming a fixed budget.

There is no authentication failure mode: an unrecognised key is ignored rather than rejected, so a request never fails with 401 because of a bad key.

Response Envelope​

Every endpoint returns a consistent JSON envelope. Integrators can rely on the same top-level shape regardless of the endpoint called.

Success​

{
  "success": true,
  "data": { ... },
  "actions": { "transactions": [...], "permissions": [...] } | null
}
  • data — Informational payload (market data, quotes, simulation results, user positions, etc.). Present on all responses; null when the endpoint only produces transaction calldata with no additional info.
  • actions — Transaction calldata and approval/permission transactions that the caller should execute on-chain. Only populated by action endpoints; null on data endpoints.
    • actions.transactions — Array of { to, data, value } objects ready to be sent as EVM transactions.
    • actions.permissions — Envelope-level array of approval/permission transactions (ERC-20 approves, credit delegations) that must be executed before the main transactions. Each entry has a human-readable description.

Note on permissions vs permissionTxns: the envelope exposes a single deduplicated actions.permissions array. Inside richer action responses (e.g. loop alternatives), each individual quote also carries its own permissionTxns — the per-quote subset needed if that specific alternative is executed. Most integrators only need actions.permissions.

Error​

{
  "success": false,
  "error": { "code": "MISSING_PARAM", "message": "marketUid is required" }
}
  • error.code — Machine-readable error code (e.g. MISSING_PARAM, INVALID_PARAM, ACTION_FAILED, NOT_FOUND, ORIGIN_FAILED).
  • error.message — Human-readable description.

The envelope is the same for every failure, so success is the only field you need to branch on. Note that a missing or malformed required parameter currently surfaces as HTTP 502 with error.code = ORIGIN_FAILED rather than a 400 — branch on success, not on the status code. See Errors & retries.

Identifiers​

Most endpoints address a market with a marketUid: lender:chainId:address, e.g. AAVE_V3:1:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2. The lender segment comes from the LenderId set and address is the underlying asset, not the receipt token. See Market identifiers.

Data (/v1/data/*)​

Cacheable market data, prices, yields, and user positions. These endpoints always return actions: null — only the data field is populated.

Actions (/v1/actions/*)​

Transaction builders organized by category:

  • Lending — deposit, withdraw, borrow, repay, mode, enable-collateral, repay-with-atoken
  • Loop — leverage, close, collateral-swap, debt-swap, migrate (cross-lender), refinance (see also Data › Loop for range calculations)
  • Swap — spot (same-chain meta-aggregator), x-chain (bridge aggregation)
  • Allocate — batch operations

All action endpoints support GET (query parameters only) and POST (query parameters + JSON body for post-trade simulation). The allocate endpoint is POST-only.

For loop and swap operations, omit account for a quote-only response (data contains quotes, actions is null), or include it to build full transaction calldata (actions is populated with ready-to-send transactions).

Action endpoints never sign or broadcast anything. They return calldata; your wallet or signer sends it. Execute actions.permissions first, then one transaction from actions.transactions (or exactly one entry from actions.alternatives where present). See the Quickstart.

Simulation (POST)​

POST the same query parameters as GET, plus a JSON body with the user's current balanceData and aprData. The response includes the standard fields plus a simulation object in data with projected post-trade health factor, borrow capacity, and APR data.

Execution Modes (lending only)​

  • direct (default): Raw protocol interaction (deposit/withdraw/borrow/repay only)
  • proxy: Routes through 1delta composer contracts

Authentication​

Optional. Without a key, requests are limited to 10 per 15 minutes. Get your key from https://auth.1delta.io/

Security Scheme Type:

apiKey

Header parameter name:

x-api-key