# Overview

**Arenas** brings real-world financing on-chain by connecting two existing systems with a single, thin piece of glue.

Arenas deploys **one contract of its own — the Credit Delegation Module (CDM)**. Everything else it uses is external and already deployed:

| Piece       | What it is                                                                                           | Whose contracts                       |
| ----------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------- |
| **Atomica** | The credit engine — approval-gated, undercollateralized financing markets.                           | **Atomica** contracts (Base)          |
| **Aave**    | An optional liquidity source, used via standard credit delegation for boosted yield.                 | **Aave v3** contracts (Base)          |
| **CDM**     | Arenas’ own **Credit Delegation Module** — routes Aave borrowing power into Atomica financing pools. | **Arenas** (the only Arenas contract) |

Arenas is **not** an Aave fork and does not run its own liquidity protocol. It uses Aave v3 and Atomica as they are, and adds the CDM to connect them.

***

### How it fits together

```mermaid
flowchart LR
    LP[Supplier] -->|supply collateral| Aave[(Aave v3 · Base)]
    Aave -->|delegated borrowing power| CDM[Arenas CDM]
    CDM -->|supply borrowed liquidity| Atomica[(Atomica · Base)]
    Atomica -->|financing| Borrowers[Borrowers]
    Atomica -->|yield| LP
```

* **Borrowers** get approval-gated credit from [**Atomica**](/atomica/key-concepts) markets — no on-chain collateral.
* **Suppliers / LPs** earn Atomica yield, and can amplify it by delegating Aave credit through the **CDM** (the [Aave Market](/arenas/aave-market) strategy).

***

### Where to start

* Understand the credit engine → [**Atomica → Key Concepts**](/atomica/key-concepts).
* The Arenas piece itself → [**Credit Delegation Module**](/arenas/credit-delegation).
* Earn boosted yield → [**Aave Market**](/arenas/aave-market).
* Build an integration → [**Build with Arenas**](/build-with-arenas/build).

***

### Networks

Arenas operates on **Base** (chain 8453), alongside the Atomica deployments on Base, Arbitrum One and Boba.


# How Arenas uses Atomica

Arenas does not have its own credit or liquidity contracts. It uses **Atomica** (Base) as the credit engine and **Aave v3** (Base) as an optional liquidity source, and adds a single contract — the **Credit Delegation Module (CDM)** — to connect them.

***

### Who owns what

| System      | Provides                                                                                    | Contracts              |
| ----------- | ------------------------------------------------------------------------------------------- | ---------------------- |
| **Atomica** | Financing markets, pools, obligations, the request → approve → draw-down → repay lifecycle. | Atomica’s own (Base)   |
| **Aave v3** | Overcollateralized supply/borrow and credit delegation.                                     | Aave’s own (Base)      |
| **Arenas**  | The **CDM**, which delegates Aave borrowing power into Atomica pools.                       | One contract — the CDM |

***

### What Atomica handles

Every Arenas financing market **is** an Atomica market. Atomica enforces:

* The shared **request → approve → draw down → repay** lifecycle.
* Fee and permission **limits**.
* One standardized engine for liquidity, disbursement, repayment and accounting.

See [**Atomica → Key Concepts**](/atomica/key-concepts) and [**Atomica Protocol**](/atomica/atomica-protocol).

***

### What Arenas adds

Arenas’ contribution is the **CDM** and the product around it:

* **Boosted yield** — the CDM lets a supplier keep collateral on Aave, delegate its borrowing power, and route the borrowed liquidity into Atomica pools to earn the spread. See [**Credit Delegation Module**](/arenas/credit-delegation) and the [**Aave Market**](/arenas/aave-market) strategy.
* **Distribution** — the app ([app.arenas.fi](https://app.arenas.fi)), lending experience ([arenas.fi](https://arenas.fi)), and the API/SDK/CLI in [**Build with Arenas**](/build-with-arenas/build).

In short: **Atomica is the credit engine, Aave is optional liquidity, and Arenas is the CDM that connects them plus the product experience on top.**


# Credit Delegation Module (CDM)

The **Credit Delegation Module (CDM)** is the **only contract Arenas deploys**. It connects two external systems — **Aave v3** (Base) for liquidity and **Atomica** (Base) for credit — so a supplier can put idle Aave collateral to work in Atomica financing pools.

***

### What it does

The CDM automates the **borrow-from-Aave, supply-to-Atomica** strategy in one place:

1. A supplier keeps collateral on **Aave v3** (earning Aave’s base supply yield).
2. They **delegate borrowing power** to the CDM using Aave’s standard credit-delegation interface.
3. The CDM **borrows from Aave** against that delegated power and **supplies the liquidity into Atomica** pools.
4. Because Atomica’s supply yield exceeds the Aave borrow rate, the supplier earns the **spread** as bonus yield — on top of the base Aave yield they keep.

```mermaid
flowchart LR
    S[Supplier] -->|1. supply collateral| Aave[(Aave v3 · Base)]
    S -->|2. approveDelegation| CDM[Arenas CDM]
    CDM -->|3. borrow onBehalfOf| Aave
    CDM -->|4. supply| Atomica[(Atomica pools · Base)]
    Atomica -->|spread / yield| S
```

***

### Aave credit delegation (the mechanism it builds on)

The CDM uses Aave’s native credit delegation — nothing forked or reimplemented:

* The supplier (**delegator**) calls `approveDelegation` on the relevant Aave **`VariableDebtToken`**, authorizing the CDM (**delegatee**) for an amount.
* The CDM calls `borrow` on the Aave **`Pool`** with the delegator’s address as `onBehalfOf`.
* Aave’s own rules still apply: eMode category must match, and a borrow that would push the delegator’s **health factor** below the liquidation threshold reverts. Collateral must be supplied before the borrow executes.

***

### Risk

This is a **leveraged** position. The borrowed amount accrues Aave interest, the delegator’s Aave collateral remains subject to Aave’s health-factor and liquidation rules, and the Atomica financing carries credit risk. The bonus only holds while Atomica yield exceeds the Aave borrow cost. See the [Aave Market](/arenas/aave-market) strategy and [Atomica Risks](/atomica/atomica-risks).

***

> **Not affiliated with Aave.** Aave v3 is a permissionless public good; Arenas uses its publicly available liquidity and the standard credit-delegation interface. Aave is one optional, external liquidity source — not the Arenas engine.


# Aave Market

The app includes an **Aave market** where you can supply supported **Aave tokens** as collateral. That collateral does more than earn Aave's base supply yield — its **borrowing power** used to fund Atomica financing pools and earn **bonus APY/APR** on top.

***

### The idea: boosted yield via credit delegation

Instead of supplying idle capital, you put your Aave collateral's **borrowing power** to work:

1. **Supply** a supported asset into the Aave market (visible in the app) — this is your collateral and earns Aave's base supply yield.
2. **Borrow against it on Aave** through **credit delegation** — your collateral's borrowing power is delegated so funds can be borrowed from Aave without withdrawing your deposit.
3. **Supply the borrowed liquidity into Atomica** financing pools.
4. **Earn the spread.** Atomica's supply yield is higher than the Aave borrow rate, so the difference is **bonus APY/APR** — earned on top of the base Aave supply yield you keep on your original collateral.

In short: **borrow from Aave, supply to Atomica.** You keep your Aave position and amplify your overall yield with the delegated credit.

> Like any leveraged position, this carries risk. The borrowed amount accrues Aave interest, your Aave collateral remains subject to Aave's health-factor and liquidation rules, and Atomica financing carries credit risk (see [Atomica Risks](/atomica/atomica-risks)). The bonus only holds while Atomica yield exceeds the Aave borrow cost.

***

### How delegation works

Credit delegation lets a supplier (the **delegator**) keep their collateral supplied while delegating borrowing power so liquidity can be borrowed and routed into Atomica. Mechanically it follows Aave's standard flow — `approveDelegation` on the relevant debt token, then a delegated `borrow`. See [Credit Delegation](/arenas/credit-delegation) for the full mechanics.

***

### Relationship to Aave

Arenas is **not partnered with, affiliated with, or endorsed by Aave**. Aave v3 is a permissionless **public good**, and Arenas simply uses the **publicly available liquidity** and the standard credit-delegation interface that anyone can access. Aave is **not** the underlying engine of Arenas — Arenas’ only contract is the [Credit Delegation Module (CDM)](/arenas/credit-delegation), and credit itself runs on the external [Atomica](/atomica/atomica-protocol) engine. Aave is one optional, external liquidity source.

***

### Aave v3 contract addresses (Base)

The canonical Aave v3 deployment on **Base** (chain id `8453`). These are **Aave's own public contracts**, not Arenas contracts — always cross-check against the official [Aave Address Book](https://github.com/bgd-labs/aave-address-book) before interacting.

| Name                      | Address                                      |
| ------------------------- | -------------------------------------------- |
| PoolAddressesProvider     | `0xe20fCBdBfFC4Dd138cE8b2E6FBb6CB49777ad64D` |
| Pool                      | `0xA238Dd80C259a72e81d7e4664a9801593F98d1c5` |
| PoolConfigurator          | `0x5731a04B1E775f0fdd454Bf70f3335886e9A96be` |
| AaveOracle                | `0x2Cc0Fc26eD4563A5ce5e8bdcfe1A2878676Ae156` |
| AaveProtocolDataProvider  | `0x0F43731EB8d45A581f4a36DD74F5f358bc90C73A` |
| UiPoolDataProviderV3      | `0x0C6BC4a12039788be08F87e87Cff87FEDbd1D386` |
| UiIncentiveDataProviderV3 | `0x91E04cf78e53aEBe609e8a7f2003e7EECD743F2B` |
| ACLManager                | `0x43955b0899Ab7232E3a454cf84AedD22Ad46FD33` |
| WrappedTokenGatewayV3     | `0xa0d9C1E9E48Ca30c8d8C3B5D69FF5dc1f6DFfC24` |
| RewardsController         | `0xf9cc4F0D883F1a1eb2c253bdb46c254Ca51E1F44` |
| Collector                 | `0xBA9424d650A4F5c80a0dA641254d1AcCE2A37057` |

> These are external, third-party addresses maintained by Aave. Arenas itself deploys only the [Credit Delegation Module (CDM)](/arenas/credit-delegation); the credit markets are [Atomica](/atomica/atomica-protocol) contracts.


# Key Concepts

Atomica is the **credit engine** underneath every Arenas Financing Market. This page defines the objects and terms used throughout the Atomica section so the rest of the docs stay short.

***

### The building blocks

| Concept                      | What it is                                                                                                                                                                                   |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Financing Market**         | The market contract for one real-world program (e.g. `Brazil – Coffee – USDC`). Holds the request → approve → receive → repay logic and routes funds between borrowers and pools.            |
| **Pool (Financing adapter)** | The liquidity side of a market. LPs deposit the asset token and receive **pool shares**; the pool supplies capital to the market when a borrower draws down.                                 |
| **Asset token**              | The single ERC-20 a market uses for both supply and repayment (typically a stablecoin such as USDC).                                                                                         |
| **Access token (NFT)**       | A borrower’s eligibility credential in a market. Owning the access token is what lets an address create requests and draw down — there is **no ERC-20 collateral** to post.                  |
| **Financing request**        | A borrower’s ask: an amount, a minimum acceptable amount, a rate ceiling (or fixed repayment), and a duration. Reviewed before any money moves.                                              |
| **Financing**                | An active loan created once an approved request is drawn down. Tracks obligations until repaid.                                                                                              |
| **Obligations**              | The live on-chain accounting of what a borrower owes on a financing: **principal**, **interest**, and **other obligations**.                                                                 |
| **Intent**                   | A standing liquidity offer from a pool — an amount available at a given rate. Draw-downs are filled from intents, cheapest first. See [Intents & Liquidity](/atomica/intents-and-liquidity). |

***

### Two kinds of financing

A request is created as one of two types, fixed at request time:

* **Interest-accrual** — interest accrues over time against a borrower-set **rate ceiling** (`maxRate`). Open-ended; repay principal and accrued interest whenever due.
* **Fixed-repayment** — the borrower commits to a single **fixed repayment amount** over a set **duration**, rather than an accruing rate.

***

### The lifecycle at a glance

Every financing follows the same path. The important detail — often misunderstood — is that **approve and receive are two separate steps**:

```mermaid
flowchart LR
    A[REQUESTED] -->|approver authorises amount| B[APPROVED]
    B -->|borrower draws down| C[ACTIVE / FILLED]
    C -->|repay principal + interest| D[Repaid]
    A -->|closeRequest| E[CLOSED]
    B -->|closeRequest| E
```

* The **approver** authorises an amount (possibly partial). This moves **no funds** — it opens a **timed receive window**.
* The **borrower** later **draws the money down themselves** inside that window, with liquidity auto-selected from lender intents.

See [Financing Request Lifecycle](/atomica/financing-request-lifecycle) for the full state machine and statuses.

***

### Undercollateralized & approval-gated

Unlike a typical money market, Atomica has **no on-chain collateral and no price-based liquidation**:

* Eligibility is the **access token**, not locked collateral.
* Every draw-down requires an **approver’s** sign-off.
* Repayment is backed by an **off-chain legal agreement**, enforced off-chain.
* A non-performing loan can be **sold on a secondary market** at a discount, with proceeds refunded to the pool’s LPs.

See [Roles & Permissions](/atomica/roles-and-permissions) for who can do what, and [Atomica Risks](/atomica/atomica-risks) for how these trade-offs are managed.

***

### Supported networks

| Network      | Chain ID | Type    |
| ------------ | -------- | ------- |
| Base         | 8453     | Mainnet |
| Arbitrum One | 42161    | Mainnet |
| Boba Network | 288      | Mainnet |
| Base Sepolia | 84532    | Testnet |
| Sepolia      | 11155111 | Testnet |


# Atomica Protocol

Arenas Financing Markets run on top of the **Atomica Protocol** — the credit engine that powers every market. Atomica defines the on-chain building blocks (markets, pools, obligations and roles) and the standard lifecycle a financing goes through, from request to repayment. You don’t interact with Atomica directly; you use an Arenas market, and Atomica enforces the rules underneath.<br>

***

### What Atomica is

Atomica is a **configurable, credit-based financing engine**. Instead of the overcollateralized, auto-liquidating model of typical money markets, Atomica implements **approval-gated, undercollateralized credit**: liquidity providers fund pools, borrowers request financing, a permissioned approver signs off, and repayment is governed by an off-chain legal agreement rather than a collateral ratio.

Every Arenas market is an Atomica market configured for a specific real-world program (for example `Brazil – Coffee – USDC`). All markets share the same engine, so they behave consistently and stay within the same protocol-level limits.

***

### Core building blocks

| Component                         | What it is                                                                                                                                                              |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **FinancingMarket**               | The market contract. Holds the borrower request/approval/draw-down/repayment logic and routes funds to and from pools.                                                  |
| **FinancingMarketAdapter (pool)** | The liquidity pool (pool-v2). LPs deposit the asset token and receive pool shares; the adapter supplies capital to the market when a financing is drawn down.           |
| **Access-token NFT**              | A borrower’s eligibility credential in a market. Owning the access token is what lets an address create requests and draw down — there is no ERC-20 collateral to post. |
| **Obligations**                   | On-chain accounting of what a borrower owes: principal, interest, and other obligations, tracked per financing.                                                         |

***

### The financing lifecycle

A financing moves through a fixed sequence of on-chain steps. Each step maps to a role and a market-contract call:

1. **Request** — the borrower calls `requestFinancing` (interest accrues over time) or `requestFixedFinancing` (a fixed repayment amount). Requests can be revised (`modifyRequest`) or withdrawn (`closeRequest`). No token approval is needed — eligibility is the access-token NFT.
2. **Review** — an **Approver** reviews the pending request and either `approveRequest` (optionally for a **partial** amount) or `declineRequest`. Approval does **not** move any funds.
3. **Draw down** — the borrower calls `receiveFinancing` to disburse an approved request. Liquidity is sourced from one or more pools by passing **lender intents** (packed `address+id` tranches) **sorted by rate ascending**, so the cheapest capital fills first. The recipient address can differ from the borrower’s wallet. Fills can be partial if pool capacity is short.
4. **Repay** — anyone (not only the borrower) can repay at any time: `repay` for a full payoff, or the fine-grained `payInterest` / `repayPrincipal` / `payOtherObligations`. Loans are effectively open-ended; repayment is enforced by the signed agreement, not by an on-chain health factor.

There is **no collateral-based liquidation**. A non-performing obligation can instead be sold on a secondary market at a discount, with the recovered amount refunded directly to the affected pool’s LPs.

***

### The liquidity side (LPs)

Liquidity providers interact with the **pool adapter**, not the borrower flow:

* **Deposit** — approve the asset token and `deposit` into the pool to receive pool shares that accrue interest as borrowers repay.
* **Withdraw** — withdrawals are a **two-step, delayed** process: `createWithdrawRequest`, then `executeWithdrawRequest` after the pool’s `withdrawDelay`. If liquidity is locked in active obligations, a request may be fulfilled proportionally.

***

### Roles

* **Market Operator** — configures the market within protocol limits and (absent a separate approver) reviews requests; earns a share of interest as a market fee.
* **Approver** — the permissioned role that approves or declines financing requests.
* **Liquidity Provider (LP)** — supplies capital to pools and earns interest and incentives.
* **Borrower** — holds the access token, creates requests, draws down, and repays.
* **Curator** — arranges liquidity and pool relationships for a market.

***

### What the protocol guarantees

Whatever a specific market configures, Atomica ensures that:

* All markets follow the same **request → approve → draw down → repay** lifecycle.
* Fees and permissions stay within predefined protocol **limits**.
* Liquidity, disbursement and repayment use the same **standardized engine and accounting**.
* Only allowlisted addresses can deploy new markets on a product.

***

### Supported networks

Atomica markets are deployed on the following networks (see **Deployed Contracts** for addresses):

| Network      | Chain ID | Type    |
| ------------ | -------- | ------- |
| Base         | 8453     | Mainnet |
| Arbitrum One | 42161    | Mainnet |
| Boba Network | 288      | Mainnet |
| Base Sepolia | 84532    | Testnet |
| Sepolia      | 11155111 | Testnet |


# Roles & Permissions

Atomica markets are **permissioned by role**. Each action in a market is gated to a specific party, and no single role can move funds on its own. This page maps every role to what it can and cannot do.

***

### The four roles

| Role                        | Responsible for                | Key actions                                                   |
| --------------------------- | ------------------------------ | ------------------------------------------------------------- |
| **Borrower**                | Requesting and repaying credit | Create / modify / close a request, draw down (receive), repay |
| **Approver**                | Credit decisions               | Approve (full or partial) or decline a request                |
| **Liquidity Provider (LP)** | Funding the market             | Deposit into a pool, request and execute withdrawals          |
| **Curator**                 | Liquidity relationships        | Arrange pools and terms that supply a market                  |

> A **Market Operator** configures the market within protocol limits and, when there is no separate Approver, also performs the review. The Operator earns a share of interest as a **market fee**.

***

### What each role can do

#### Borrower

* Must hold the market’s **access token (NFT)** — this, not collateral, is the eligibility check. The NFT is never transferred by these actions; only ownership is checked.
* Can **create** a request (`REQUESTED`), **modify** it while still `REQUESTED`, or **close** it while `REQUESTED` or `APPROVED`.
* Can **draw down** an approved request during its receive window. Funds can be sent to a **recipient address that differs** from the borrower’s wallet.
* Cannot self-approve. Cannot draw down more than the approved amount.

#### Approver

* Reviews pending requests and either **approves** — optionally for a **partial** amount — or **declines**.
* Approval **authorises an amount and opens a timed receive window**; it does **not** transfer funds.
* Is a distinct address from the borrower; a borrower can never approve their own request.

#### Liquidity Provider (LP)

* **Deposits** the asset token into a pool and receives **pool shares** that accrue value as borrowers repay.
* **Withdraws** via a two-step, delayed flow (request → wait → execute). See [Withdraw](/atomica/financing-markets/withdraw).
* Bears the market’s credit risk: LP share value can fall if borrowers default.

#### Curator

* Arranges the **pools and liquidity terms** that fund a market, and the intents that make capital available to borrowers.
* Works with the Market Operator on pool configuration and incentives.

***

### Separation of powers

The security of an Atomica market comes from splitting authority across roles:

```mermaid
flowchart LR
    B[Borrower] -->|requests| M[(Financing Market)]
    A[Approver] -->|authorises amount| M
    B -->|draws down within window| M
    L[LP / Pool] -->|supplies liquidity via intents| M
    M -->|disburses to recipient| R[Recipient]
```

* The **borrower** asks, but cannot authorise.
* The **approver** authorises, but does not move or hold funds.
* The **LP / pool** funds, but does not decide who borrows.
* The **market contract** enforces that all three line up before a single token is disbursed.

***

### Permission notes

* **Access-token gating:** only the access-token owner (or an address on the request’s trigger list) may request or receive.
* **Partial approvals:** the approved amount always stays within the borrower’s requested `[minAmount, amount]` band.
* **Receive window:** the window is snapshotted at approval time and stays fixed even if market configuration changes afterward.

See [Financing Request Lifecycle](/atomica/financing-request-lifecycle) for how these permissions play out step by step.


# Financing Request Lifecycle

A financing is not a single transaction — it moves through a **state machine**, and each transition is performed by a different role. The step most people miss is that **approval and draw-down are separate**: an approver authorises an amount, and the borrower later draws it down themselves.

***

### The states

```mermaid
stateDiagram-v2
    [*] --> REQUESTED: borrower creates request
    REQUESTED --> REQUESTED: modifyRequest
    REQUESTED --> APPROVED: approver authorises (full or partial)
    REQUESTED --> CLOSED: closeRequest / declined
    APPROVED --> ACTIVE: borrower draws down (receive)
    APPROVED --> CLOSED: closeRequest
    ACTIVE --> Repaid: repay principal + interest
    Repaid --> [*]
```

| State         | Meaning                                                                              | Who moves it next      |
| ------------- | ------------------------------------------------------------------------------------ | ---------------------- |
| **REQUESTED** | Request created, awaiting review. Can still be edited or cancelled.                  | Approver (or borrower) |
| **APPROVED**  | An amount is authorised and a **timed receive window** is open. No funds have moved. | Borrower               |
| **ACTIVE**    | Financing drawn down; obligations accrue until repaid.                               | Borrower (repay)       |
| **CLOSED**    | Request cancelled or declined before draw-down.                                      | —                      |

***

### Step 1 — Request

The borrower creates a request against a market, choosing:

* **Amount** and **minimum amount** — the acceptable fill band `[minAmount, amount]`.
* **Type** — interest-accrual (with a **rate ceiling**) or fixed-repayment (a **fixed repay amount** over a **duration**).
* **Recipient** — where funds should land (defaults to the access-token owner).

No token approval is needed; eligibility is the **access token (NFT)**. While in `REQUESTED`, the borrower may `modifyRequest` or `closeRequest`.

***

### Step 2 — Review (approve ≠ fund)

An **Approver** reviews the request and either:

* **Approves** it — optionally for a **partial** amount within the requested band — which **opens a receive window** (an earliest and latest time to draw down), or
* **Declines** it.

> **Approval moves no money.** It authorises an amount and starts a clock. This is the key difference from collateral-based lending, where borrowing is instantaneous.

The receive window is **snapshotted at approval** and does not change even if the market is reconfigured later.

***

### Step 3 — Draw down (receive)

Inside the receive window, the **borrower** draws the money down. Liquidity is sourced from the pool’s **lender intents**, selected automatically **cheapest-rate-first** — the borrower does not hand-pick lenders in the standard flow. See [Intents & Liquidity](/atomica/intents-and-liquidity).

A draw-down can **partially fill** if pool capacity is short, and the borrower can draw again (up to the approved amount) while the window is open. Because on-chain capacity can change between approval and draw-down, a fill is only final once the transaction settles. Possible outcomes:

| Outcome              | Meaning                                                             |
| -------------------- | ------------------------------------------------------------------- |
| **Success**          | Financing becomes `ACTIVE`.                                         |
| **Lack of capacity** | Not enough lender liquidity available right now.                    |
| **Rate exceeded**    | The only available liquidity is priced above the request’s ceiling. |
| **Below minimum**    | The achievable fill is under the request’s `minAmount`.             |

***

### Step 4 — Repay

Once `ACTIVE`, **anyone** (not only the borrower) can repay — in full or in part — at any time. Repayment is enforced by the **off-chain agreement**, not by an on-chain health factor, so there is no price-based liquidation. See [Repay](/atomica/financing-markets/repay).

If a loan is not repaid, the obligation can be **sold on a secondary market** at a discount, with proceeds refunded to the affected pool’s LPs.


# Intents & Liquidity

When a borrower draws down an approved financing, the money doesn’t come from a single undifferentiated pool balance — it comes from **intents**. An intent is a standing offer of liquidity from a pool at a specific rate. This page explains how intents fill a draw-down.

***

### What an intent is

An **intent** is a pool’s commitment to lend:

| Property             | Meaning                                             |
| -------------------- | --------------------------------------------------- |
| **Source pool**      | The financing adapter (pool) providing the capital. |
| **Available amount** | How much of the intent is still unfilled.           |
| **Rate**             | The rate at which this capital is offered.          |
| **Validity window**  | The time range during which the intent can be used. |

A single market can have **many intents** at different rates, from one or several pools.

***

### Cheapest-first filling

When a borrower draws down, Atomica fills the requested amount from intents **sorted by rate, ascending** — the cheapest capital is used first, then the next cheapest, and so on until the draw-down amount is covered:

```mermaid
flowchart LR
    R[Draw-down: need 100k] --> S{Sort intents by rate}
    S --> I1[Intent A · 6% · 40k]
    S --> I2[Intent B · 8% · 40k]
    S --> I3[Intent C · 11% · 50k]
    I1 --> F[Fill 40k @6%]
    I2 --> F2[Fill 40k @8%]
    I3 --> F3[Fill 20k @11%]
```

* Each intent fills to capacity before the next is used.
* Filling stops once the draw-down amount is reached — leftover intents stay available for others.
* The borrower’s effective rate is the **blended** rate of the intents that filled the loan.

***

### Automatic selection

In the standard borrower flow, **intent selection is automatic**. The app picks the optimal set of intents and packs them into the draw-down transaction; the borrower simply confirms. A read-only preview may show the selected capacity, the number of intents used, and the resulting rate. Manual intent picking exists only as an advanced option.

***

### Guardrails

Because intents are priced offers with limited capacity, a draw-down respects the request’s terms:

| Guardrail          | Effect                                                                                                                                                          |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Rate ceiling**   | For interest-accrual requests, intents priced above the borrower’s ceiling are not used (and if that’s all there is, the draw-down fails with *rate exceeded*). |
| **Minimum amount** | If the achievable fill is below the request’s `minAmount`, the draw-down is rejected rather than partially settled.                                             |
| **Capacity**       | If total usable intent capacity is short, the draw-down either partially fills or fails with *lack of capacity*.                                                |
| **Validity**       | Expired or not-yet-valid intents are skipped.                                                                                                                   |

Because on-chain intent capacity can be consumed by other borrowers between approval and draw-down, the final fill is only known once the transaction settles — see [Financing Request Lifecycle](/atomica/financing-request-lifecycle).

***

### Where intents come from

Intents are created on the **liquidity side** of a market. LPs [supply](/atomica/financing-markets/supply) capital into a pool, and the pool (arranged by a **Curator**) makes that capital available as intents. This is how Arenas connects **passive LP deposits** to **program-specific borrower demand** without either side pricing the other manually.


# Financing Markets

Financing Markets are **Atomica credit markets** configured for specific real-world financing programs and **governed by a Market Operator**.\
Each market has its own liquidity, interest model and borrowers set, but all of them run on the same Atomica financing products described on the Atomica Protocol page.

***

### What is a Financing Market?

A Financing market is a dedicated financing pool for a specific use case, for example:

> `Brazil – Coffee – USDC`

A market can define:

* **Seniority of tranches repayment** (whether it is a higher risk (junior pool - higher interest and later repayments), or a lower risk (senior pool - lower interest and earlier repayments),
* **What is being financed** (sector / type of good (service) / program),
* **Which base asset is used** for deposits and obligations (capital token - i.e. USDC),
* **How interest is priced** for borrowers,
* **Who is** **allowed to borrow** in that market.
* **What is being financed** (sector / geography / program),
* **Which collateral is used** for deposits and loans (capital token)

Under the hood, the market is a configurable smart contract that follows the rules of the underlying Atomica financing product.

***

### Roles in a Financing Market

* **Market Operator**
  * Sets up the market parameters within product limits.
  * Approves or rejects **financing requests**.
  * Earns a share of interest as a **market fee**.
* **Liquidity Providers (Lenders)**
  * Supply the capital token to the market and receive **LP tokens**.
  * Earn interest (and possible incentives) from funded obligations
  * Are subject to the market’s **liquidity and withdrawal rules**.
* **Borrowers**
  * Create a **financing application** (borrower specific NFT) on a particular financing market.
  * Submit **financing requests** with desired obligation amount. Requests are based on a specific financing application and linked to it.
  * Sign a **real-world** contract (financing agreement) for that market’s program.
  * Receive funds only after **Market Operator** (or **Approver**) **approval** and sufficient liquidity in market pools. It can be a partial approval of the requested amount, and it can be borrowed a part of the approved amount up to available liquidity and other financing request parameters/ limitations.

Financing Markets are therefore the place where Arenas connects on-chain liquidity with **off-chain**, **program-specific** **financing terms**/ **agreements**, all powered by the Atomica engine.


# Supply

Deposit the asset token into a Financing Market pool and earn yield as borrowers repay, all powered by the Atomica engine.

Supplying is how **Liquidity Providers** fund a Financing Market. You deposit the market’s asset token (e.g. USDC) into a **pool** and receive **pool shares** that grow in value as borrowers pay interest back into the pool.

***

### How it works

1. **Approve** the asset token for the pool’s financing adapter.
2. **Deposit** the asset into the pool. Your deposit becomes available to borrowers as **intents** (see [Intents & Liquidity](/atomica/intents-and-liquidity)).
3. The pool **mints pool shares** to you, representing your claim on the pool’s assets plus accrued yield.

```mermaid
sequenceDiagram
    participant LP as Liquidity Provider
    participant Adapter as Financing adapter (pool)
    participant Pool as Financing pool

    LP ->> Adapter: 1. Approve asset token
    LP ->> Adapter: 2. Deposit assets (ERC-20)
    Adapter -->> Pool: 3. Supply liquidity (becomes intents)
    Pool -->> LP: 4. Mint pool shares
```

***

### What you earn

Your pool shares accrue value from:

* **Interest** borrowers pay on active financings.
* Optional **upfront incentives** borrowers pay to attract capital.
* Optional **reward programs** funded by the market or third parties.

There is no fixed APY — returns track the actual performance of the market’s loans.

***

### Things to know

* **Capacity caps.** A pool may have a deposit **cap**; when reached, deposits are paused until capacity frees up. `cap = 0` means unlimited.
* **Pool phases.** Some pools only accept deposits in certain phases (e.g. an accumulation window). Deposits revert when the current phase disallows them.
* **Credit risk.** Pool share value can fall if borrowers default — supplying is not risk-free. See [Atomica Risks](/atomica/atomica-risks).
* **Withdrawals are delayed.** Redeeming is a two-step, time-locked process — see [Withdraw](/atomica/financing-markets/withdraw).


# Withdraw

Redeem your pool shares for the underlying asset plus accrued yield, via a two-step delayed withdrawal.

Withdrawing converts your **pool shares** back into the underlying asset, including accrued yield. Unlike supplying, withdrawing is always a **two-step, time-locked** process — even when the delay is set to zero.

***

### The two steps

```mermaid
sequenceDiagram
    participant LP as Liquidity Provider
    participant Adapter as Financing adapter (pool)

    LP ->> Adapter: 1. createWithdrawRequest (locks shares)
    Note over LP,Adapter: wait for withdrawDelay
    LP ->> Adapter: 2. executeWithdrawRequest (after delay)
    Adapter -->> LP: 3. Return assets + accrued yield
```

1. **Create a withdrawal request.** This locks the shares you want to redeem. There is **one active request per LP**, and it **cannot be cancelled** once created.
2. **Execute the request** after the pool’s `withdrawDelay` has elapsed. The same wallet that created the request must execute it, and receives the assets.

***

### Why the delay

The delay lets the pool manage liquidity that is temporarily locked in active financings. If much of the pool is lent out, a request may be:

* **Fulfilled proportionally** — you receive the redeemable share now, with the remainder following as loans are repaid, or
* **Delayed** until enough borrowers repay.

The protocol always returns either assets or shares; it does not freeze your funds without a claim.

***

### Things to know

* **One-way lock.** `createWithdrawRequest` locks your shares immediately and cannot be reversed — plan the amount before submitting.
* **Same wallet executes.** Only the wallet that created the request can execute it, after the delay.
* **Availability.** Withdrawals are subject to unborrowed liquidity in the pool at execution time.

See [Supply](/atomica/financing-markets/supply) for the deposit side and [Intents & Liquidity](/atomica/intents-and-liquidity) for how your capital is put to work in between.


# Borrow

Request approval-gated, undercollateralized credit from a Financing Market — request, get approved, then draw down yourself. Powered by the Atomica engine.

Borrowing on Arenas gives you access to liquidity **without posting on-chain collateral**. Instead of an instant, collateral-backed loan, borrowing is **approval-gated** and happens in two distinct stages: an approver **authorises** an amount, and then **you draw it down**.

***

### Before you start

* You need the market’s **access token (NFT)** — this is your eligibility, in place of collateral.
* You sign the market’s **real-world financing agreement** off-chain. This legal contract, not a collateral ratio, is what backs repayment.

***

### The flow

```mermaid
sequenceDiagram
    participant Borrower
    participant Market as Financing Market
    participant Approver
    participant Pool as Pools / intents

    Borrower ->> Market: 1. requestFinancing (amount, terms)
    Approver ->> Market: 2. approveRequest (full or partial) → opens receive window
    Note over Borrower,Market: approval moves NO funds
    Borrower ->> Market: 3. receiveFinancing (draw down within window)
    Pool -->> Market: 4. Fill from intents (cheapest rate first)
    Market -->> Borrower: 5. Disburse to recipient address
```

#### 1. Request

Create a **financing request** specifying the amount you want, a **minimum acceptable amount**, and either:

* a **rate ceiling** (interest-accrual financing — interest accrues over time), or
* a **fixed repayment amount** over a set **duration** (fixed-repayment financing).

You can edit or cancel the request while it is still pending.

#### 2. Approval (no funds move yet)

An **Approver** reviews the request and either approves it — possibly for a **partial** amount — or declines it. Approval **does not transfer money**. It authorises an amount and **opens a timed receive window** (an earliest and latest time to draw down).

> This is the single most important difference from collateral lending: approval and funding are **separate**. You are cleared to borrow, but you pull the funds yourself.

#### 3. Draw down (receive)

Within the receive window, **you** call draw-down. Liquidity is assembled automatically from the pool’s **intents**, cheapest rate first (see [Intents & Liquidity](/atomica/intents-and-liquidity)) — you don’t pick lenders. Funds are sent to the **recipient address** on the request, which can differ from your wallet.

A draw-down may **partially fill** if capacity is short; you can draw again up to the approved amount while the window is open. Because capacity can change between approval and draw-down, the fill is only final once the transaction settles:

| Outcome              | Meaning                                           |
| -------------------- | ------------------------------------------------- |
| **Success**          | Financing is now `ACTIVE`.                        |
| **Lack of capacity** | Not enough lender liquidity right now.            |
| **Rate exceeded**    | Available liquidity is priced above your ceiling. |
| **Below minimum**    | Achievable fill is under your `minAmount`.        |

***

### Repayment & risk

* Repay any time — see [Repay](/atomica/financing-markets/repay). Loans are open-ended and governed by the signed agreement, not a health factor.
* There is **no price-based liquidation**. If a loan goes unpaid, the obligation can be **sold on a secondary market** at a discount, with proceeds refunded to the pool’s LPs.

***

### At a glance

| Stage               | Who acts | Funds move?                      |
| ------------------- | -------- | -------------------------------- |
| Request             | Borrower | No                               |
| Approve / decline   | Approver | No                               |
| Draw down (receive) | Borrower | **Yes** — disbursed to recipient |
| Repay               | Anyone   | Yes — back into the pool         |

For the complete state machine and statuses, see [Financing Request Lifecycle](/atomica/financing-request-lifecycle).


# Repay

Repay an active financing — in full or in part — against live on-chain obligations. Anyone can repay, at any time.

Repaying settles an **active financing**. There is no health factor and no forced liquidation clock — repayment is driven by the off-chain agreement — but interest keeps accruing on interest-accrual loans, so the payoff amount grows until you pay.

***

### What you owe

A financing’s debt is tracked on-chain as **obligations**, split into:

* **Principal** — the amount drawn down.
* **Interest** — accrued charges (for interest-accrual financings).
* **Other obligations** — any additional amounts defined by the market.

The live obligations are the source of truth for an exact payoff — a displayed “left to repay” figure is only an estimate between blocks.

***

### Ways to repay

```mermaid
sequenceDiagram
    participant Payer
    participant Market as Financing Market

    Payer ->> Market: 1. Approve asset token (if allowance short)
    Payer ->> Market: 2. repay (full) — or payInterest / repayPrincipal
    Market -->> Market: 3. Update obligations, route funds to pool
```

| Method                    | Effect                                                      |
| ------------------------- | ----------------------------------------------------------- |
| **Repay (full)**          | Pay off principal + interest + other obligations in one go. |
| **Pay interest**          | Clear accrued interest only.                                |
| **Repay principal**       | Reduce outstanding principal.                               |
| **Pay other obligations** | Settle any additional obligations.                          |

Repayment first requires an ERC-20 **approve** of the asset token to the market if your allowance is short.

***

### Things to know

* **Anyone can repay.** Repayment is not restricted to the borrower — any address can pay down a financing.
* **Partial repayment is allowed.** You don’t have to clear the whole loan at once.
* **Repaid funds return to the pool**, increasing the value of LP shares for suppliers.
* **No collateral liquidation.** If a loan goes unpaid, recovery runs through the **off-chain agreement**; the obligation may be **sold on a secondary market** at a discount, with proceeds refunded to the affected pool’s LPs.

See [Borrow](/atomica/financing-markets/borrow) for how a financing is created and [Financing Request Lifecycle](/atomica/financing-request-lifecycle) for the full state machine.


# Atomica Risks

Arenas offers decentralised access to the liquidity but the process is not without risks. Robust risk management measures, including smart contract audits and carefully set risk parameters, are in place to help mitigate risks. Below is an overview of key risks and mitigation efforts.

### Smart Contract Risk

Smart contracts can contain software bugs or other vulnerabilities within the protocol code and the underlying tokens. To mitigate these risks, Arenas has undergone multiple external third-party professional audits. Additionally, the protocol plans to run a continuous bug bounty program to incentivize external developers to identify and report any issues they may find so they can be fixed.

### Oracle Risk

Arenas relies on third-party oracles for price feeds and external data, such as redemption ratios for liquid staking tokens. This reliance introduces potential risks such as incorrect valuations if an oracle fails or is compromised. To reduce this risk, Arenas uses decentralised oracles like Chainlink, which provide tamper-resistant data feeds, greater reliability, and security measures.

### Repayment Risk

As Arenas use undercollateralized financing and off-chain signed financing agreement there is always a risk of a partial repayment of the financing principal and/ or interest, or a total non repayment.

Partially such a risk is mitigated by the use of the financing request approval, at which stage the borrower should be inspected thoroughly. But even a good borrower can have financial troubles in the future.\
For such a case there is another mitigation possibility - a non performing obligation liquidation and the sales process on the secondary markets. A discounted value after the obligation being sold is paid back directly to liquidity providers.

<br>


# Atomica FAQ

#### How is this different from typical DeFi lending protocols like Aave?

Traditional DeFi money markets are **overcollateralized**: you lock more value in collateral than you borrow, and on-chain liquidations enforce repayment.\
Arenas Financing markets are **credit-based and approval-gated**:

* **No on-chain collateral**.
* **Market Operator** (or **Approver**) approval is required for obligations.
* Every loan is backed by a **real-world legal agreement**, not just smart-contract rules.

***

#### Do I need to provide on-chain collateral to borrow?

No. Borrowers **do not** post on-chain collateral.\
Instead, you:

1. Create a **financing application** and financing request.
2. Sign a **real-world financing agreement contract** off-chain.
3. Wait for **Market Operator** (or **Approver**) approval and disbursement.

***

#### What happens if a borrower does not repay?

Because there is no on-chain collateral to liquidate:

* The protocol will show the loan as **in default** on-chain.
* Recovery relies on the **off-chain enforcement** of the signed loan agreement.
* Losses from defaults can affect the **value of lender LP tokens** in the affected pool.
* Liquidated obligation can be sold on a secondary market at a discount and the earned amount will be refunded to the affected pool.

Exact processes for handling defaults depend on the legal and operational framework of each market.

***

#### Can I withdraw my funds at any time as a lender?

You can **request a withdrawal at any time**, but:

* Withdrawals are **subject to available liquidity** in the pool.
* If much of the pool is lent out, your request may be:
  * **Partially fulfilled**, with the rest staying as LP tokens.
  * **Delayed** until more loans are repaid.

The protocol always returns either assets or LP tokens; it does not “freeze” your funds without a claim.

***

#### How do borrowers receive the funds?

After a financing request is approved:

* The executor (you or a designated address) calls the protocol to **initiate the obligation**.
* The **Financing Market Adapter** sends the obligation amount to the recipient address specified in the financing request.

This address can be different from the borrower’s own wallet if the deal structure requires it.

***

#### How is interest for lenders generated?

Lenders earn from:

* **Interest payments** from borrowers on active loans.
* Potential **upfront incentives** borrowers pay to attract more capital.
* Optional **reward programs** funded by the protocol or third parties.

All of this is reflected in the **growing value of LP tokens** over time.

***

#### Who can be a Market Operator?

A Market Operator is a **permissioned role** responsible for:

* Reviewing financing requests if there is no separate financing Approver role.
* Approving or rejecting new financing requests.
* Monitoring portfolio quality and market configuration.
* Making agreements with Pool Curators to attract liquidity to the market.
* Support market operational activity by making control over upgradable settings.

The specific criteria for who can act as a Market Operator and how they are appointed depend on the specific market and governance setup.

***

#### Is yield guaranteed?

No. Yield is **not guaranteed**.

* If borrowers repay on time, lenders can earn **interest and rewards**.
* If borrowers default, or if markets change, returns may be **lower than expected or negative**.

Always evaluate the risks before supplying or borrowing.

***

#### Where can I see the contract addresses?

All official contract addresses are listed in the **“Deployed Contracts”** section of the docs.\
Always verify that the address you interact with matches the documented one for your network


# Overview

Arenas exposes its credit protocol as a **developer platform**, so you can embed lending, launch markets, and fund them without writing Solidity. This section covers the API, SDK, CLI, and MCP surfaces.

***

### The surfaces

| Surface                                                   | Use it for                                                                                                                                                                   |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**REST API**](/build-with-arenas/api-reference)          | Read markets, pools, requests, financings and intents; build any UI or backend. Curated JSON with normalized amounts and millisecond timestamps.                             |
| [**SDKs & Tooling**](/build-with-arenas/sdks-and-tooling) | Typed helpers for calldata, unit conversion, and contract reads on top of the API and ABIs.                                                                                  |
| [**CLI**](/build-with-arenas/cli)                         | Script and automate the same flows from a terminal or CI.                                                                                                                    |
| **MCP**                                                   | Agent-native access at `mcp.atomica.org` — skills, primitives and integration bundles for AI-assisted builds. See [SDKs & Tooling](/build-with-arenas/sdks-and-tooling#mcp). |

***

### Authentication

Every read call is scoped to an **arena** by an `arenaKey`. Pass it as a query parameter or a header:

```bash
# query param
curl "$ARENAS_API/lending/markets?arenaKey=$ARENA_KEY"

# or header
curl -H "X-Arena-Key: $ARENA_KEY" "$ARENAS_API/lending/markets"
```

Write actions are on-chain transactions signed by the user’s wallet — the API and SDK give you the **calldata and ABIs**, your app sends the transaction.

***

### Pick your journey

Arenas has three builder journeys, mapped to the three sides of a market:

| You are…                  | You want to…                 | Start here                                          |
| ------------------------- | ---------------------------- | --------------------------------------------------- |
| **Borrower / Builder**    | Embed credit in your product | [Embed Credit](/build-with-arenas/embed)            |
| **Supplier / Originator** | Launch a white-label market  | [Launch a Market](/build-with-arenas/launch-market) |
| **Liquidity Provider**    | Fund markets and earn yield  | [Fund Markets](/build-with-arenas/fund-markets)     |

***

### How reads and writes fit together

```mermaid
flowchart LR
    App[Your app / backend] -->|arenaKey| API[Arenas REST API]
    API -->|markets, pools, requests, intents| App
    App -->|ABIs + calldata| Wallet[User wallet]
    Wallet -->|signed tx| Chain[(FinancingMarket / Pool contracts)]
    App -->|poll after tx| Sync[/provisioning-sync/]
```

Reads come from the curated API; writes are wallet transactions against the [Atomica](/atomica/atomica-protocol) contracts. After a write, poll the indexer (`/provisioning-sync/last-synced-blocks`) before refetching so lists reflect the new state.


# Embed Credit (Borrowers & Builders)

Embed approval-gated credit directly in your product — let your users request financing, draw it down, and repay, without them ever touching a contract UI. This is the **borrower side** of a market, driven by the [API](/build-with-arenas/api-reference) for reads and wallet transactions for writes.

***

### The borrower flow

```mermaid
flowchart LR
    R[requestFinancing] --> A[approveRequest]
    A --> D[receiveFinancing]
    D --> P[repay]
```

| Step         | Who      | Contract call                                | Notes                                                          |
| ------------ | -------- | -------------------------------------------- | -------------------------------------------------------------- |
| 1. Request   | Borrower | `requestFinancing` / `requestFixedFinancing` | Needs the market’s **access token (NFT)** — no ERC-20 approve. |
| 2. Approve   | Approver | `approveRequest` / `declineRequest`          | Opens a timed receive window; **moves no funds**.              |
| 3. Draw down | Borrower | `receiveFinancing`                           | Fills from intents, cheapest first (auto-selected).            |
| 4. Repay     | Anyone   | `repay` / `payInterest` / `repayPrincipal`   | Requires ERC-20 `approve` to the market.                       |

See the [Financing Request Lifecycle](/atomica/financing-request-lifecycle) for the full state machine.

***

### 1. Discover markets and eligibility

```bash
# markets your arena exposes
curl -H "X-Arena-Key: $ARENA_KEY" "$ARENAS_API/lending/markets"
# access-token (NFT) contracts that gate borrowing, per chain
curl -H "X-Arena-Key: $ARENA_KEY" "$ARENAS_API/arena/access-tokens"
```

A user can request in a market only if they own one of that market’s access tokens.

***

### 2. Create a request

Build a `requestFinancing` (interest-accrual) or `requestFixedFinancing` (fixed-repayment) transaction against the **market address** (`market.id`). Key inputs:

* `amount` and `minAmount` — the acceptable fill band (denormalize by `assetToken.decimals`).
* `maxRate` (accrual) — annual APR converted to a per-second `1e18` rate; or `repayAmount` + `duration` (fixed).
* `recipient` — where funds land; `0x0` defaults to the access-token holder.

While `status = REQUESTED (0)`, the borrower can `modifyRequest` or `closeRequest`.

***

### 3. Draw down after approval

Once `status = APPROVED (1)` and inside the window (`earliestReceiveTs`…`latestReceiveTs`, in ms), call `receiveFinancing(requestId, intents)`:

* Read `market.intents[]`, keep usable ones, **sort by rate ascending**, and pack `(adapter, intentId)` into `bytes32[]` up to `market.tranchesLimit`.
* In the standard flow, **intent selection is automatic** — the app picks the optimal set and shows a read-only preview.
* Simulate first: the call returns `(financingId, amount, err)`; a tx can mine yet still report `LACK_OF_CAPACITY`, `MAX_RATE_EXCEEDED`, or `BELOW_MIN_AMOUNT`.

See [Intents & Liquidity](/atomica/intents-and-liquidity).

***

### 4. Repay

Read live obligations on-chain (`interestObligations` + `principalObligations`) for an exact payoff — don’t trust the API `leftToRepay` snapshot. Then `approve` the asset token to the market and call `repay` (full) or `payInterest` / `repayPrincipal` (partial). Any address can pay.

***

### After every write

Poll `GET /provisioning-sync/last-synced-blocks` until the transaction’s block is indexed, then refetch markets/requests so your UI reflects the new state.


# Launch a Market (Suppliers & Originators)

Originators run **white-label financing markets**: you own the borrowers and the economics, Arenas provides the engine. A market is an [Atomica](/atomica/atomica-protocol) `FinancingMarket` configured for one real-world program (e.g. `Brazil – Coffee – USDC`).

***

### What a market defines

| Parameter                           | Role                                                                 |
| ----------------------------------- | -------------------------------------------------------------------- |
| **Asset token**                     | The ERC-20 used for supply and repayment (e.g. USDC).                |
| **Approver**                        | Address allowed to approve/decline financing requests.               |
| **Operator**                        | Configures the market and earns a share of interest as a market fee. |
| **Access tokens**                   | The NFT list that gates who may borrow.                              |
| **tranchesLimit**                   | Max intents (pool tranches) a single draw-down can pull from.        |
| **exposureCap**                     | Max total outstanding principal.                                     |
| **approveExpiry / approveCooldown** | Approval window and pacing rules (ms).                               |
| **liquidationGracePeriod**          | Grace before a defaulted financing is liquidation-eligible.          |

These surface on `GET /lending/markets` per market, so your ops UI can read the live configuration.

***

### Operating a market

Once live, the two ongoing responsibilities are **review** and **monitoring**:

```mermaid
flowchart LR
    Inbox[Approver inbox] --> Rev{Review request}
    Rev -->|approveRequest| Win[Receive window opens]
    Rev -->|declineRequest| X[Declined]
```

* **Review inbox** — read each market’s `requests[]` where `status = REQUESTED (0)`, then call `approveRequest` (optionally a partial amount within `[minAmount, amount]`) or `declineRequest`. Approval opens the receive window; it does **not** move funds.
* **Monitor** — watch `financings[]` (`ACTIVE` / `REPAID` / `LIQUIDATED`), `totalOutstandingPrincipal`, and `exposureCap` to manage portfolio quality.
* **Attract liquidity** — coordinate with **Curators / LPs** so the market has intents to draw from (see [Fund Markets](/build-with-arenas/fund-markets)).

See [Roles & Permissions](/atomica/roles-and-permissions) for the operator/approver split.

***

### Market creation

Markets are deployed from a factory on top of an Atomica product that sets the shared limits (fee caps, withdrawal rules, and the allowlist of who may create markets). Deploying a new market and its pools is an onboarding step handled with the Arenas team.

> **No-code market setup** (a provisioning UI for Originators) is on the roadmap. Until then, market provisioning is done with Arenas support plus the [API](/build-with-arenas/api-reference), [CLI](/build-with-arenas/cli), and contract ABIs from `GET /abis/current`.


# Fund Markets (Liquidity Providers)

Liquidity Providers supply capital to a market’s **pool** and earn yield as borrowers repay. Programmatically, funding is the **pool-adapter** flow: deposit for shares, and a two-step delayed withdrawal.

***

### Discover pools

```bash
# pools your arena exposes
curl -H "X-Arena-Key: $ARENA_KEY" "$ARENAS_API/lending/pools"
# an account's positions, shares, and pending withdrawals
curl -H "X-Arena-Key: $ARENA_KEY" "$ARENAS_API/lending/pools/list/$ACCOUNT"
```

Use a pool where the item exposes an `adapterInfo.address` — that adapter is the contract you interact with (not the pool share-token address).

***

### Deposit

```mermaid
flowchart LR
    A[approve asset → adapter] --> D[deposit → adapter]
    D --> S[receive pool shares]
```

1. `approve` the **asset token** to the adapter address.
2. `deposit` into the adapter to receive pool shares.

Before submitting, check the adapter’s `cap` vs `totalDeposited` (`cap = 0` means unlimited) and confirm the pool phase currently allows deposits.

***

### Withdraw (two-step, delayed)

Withdrawal is always two on-chain steps, even when the delay is zero:

1. `createWithdrawRequest` — locks your shares (approve the **pool share** token to the adapter first). One active request per LP; **not cancellable**.
2. `executeWithdrawRequest` — after `withdrawDelay` elapses, the same wallet executes and receives assets.

See [Supply](/atomica/financing-markets/supply) and [Withdraw](/atomica/financing-markets/withdraw) for the mechanics.

***

### How your capital is used

Deposited liquidity is offered to borrowers as **intents** — priced offers filled cheapest-first when a borrower draws down. Your yield tracks the interest borrowers pay on the intents your pool fills. See [Intents & Liquidity](/atomica/intents-and-liquidity).

***

### Boosted yield via Aave

LPs can amplify returns by supplying Aave collateral, delegating its borrowing power, and routing the borrowed liquidity into Atomica pools to earn the spread. See the [Aave Market](/arenas/aave-market) strategy and [Credit Delegation](/arenas/credit-delegation).

***

### After every write

Poll `GET /provisioning-sync/last-synced-blocks` until your transaction’s block is indexed, then refetch `pools/list/:account` so balances and pending-withdrawal state are current.


# CLI

The Arenas CLI scripts the same flows as the [API](/build-with-arenas/api-reference) and [SDK](/build-with-arenas/sdks-and-tooling) from a terminal or CI — useful for market operations, monitoring, and automation.

***

### Configuration

The CLI is scoped to an arena the same way the API is — with an `arenaKey` — plus a signer for write operations:

| Setting               | Purpose                                          |
| --------------------- | ------------------------------------------------ |
| `ARENA_KEY`           | Scopes reads/writes to your arena.               |
| `ARENAS_API`          | API base URL (see your arena’s `/swagger`).      |
| Signer key / keystore | Required only for write commands (transactions). |

Keep signer material in environment variables or a keystore — never commit it.

***

### What you can do

Read operations mirror the API surface:

* List **markets**, **pools**, **financings**, and per-account **positions**.
* Inspect **requests** and their status, and pending **intents**.
* Check **indexer sync** (`last-synced-blocks`) after writes.

Write operations mirror the role flows (each is an on-chain transaction):

| Role     | Actions                                      |
| -------- | -------------------------------------------- |
| Borrower | request · modify · close · receive · repay   |
| Approver | approve · decline                            |
| LP       | deposit · create-withdraw · execute-withdraw |

See [Embed Credit](/build-with-arenas/embed), [Launch a Market](/build-with-arenas/launch-market), and [Fund Markets](/build-with-arenas/fund-markets) for what each action does.

***

### Typical use

```bash
# read: list markets in your arena
arenas markets list --arena-key "$ARENA_KEY"

# monitor: an approver's pending review inbox
arenas requests list --status requested --arena-key "$ARENA_KEY"

# after a write: wait for the indexer before refetching
arenas sync status --arena-key "$ARENA_KEY"
```

> Command names above are illustrative. For the exact commands and flags available in your environment, run the CLI’s built-in help, and use the [MCP](/build-with-arenas/sdks-and-tooling#mcp) as the authoritative source for flow logic.


# SDKs & Tooling

Beyond the raw [REST API](/build-with-arenas/api-reference), Arenas offers tooling to make integration faster — typed helpers, agent-native access, and the shared contract ABIs.

***

### Contract ABIs

The API serves the current contract ABI map so you don’t hardcode fragments:

```bash
curl -H "X-Arena-Key: $ARENA_KEY" "$ARENAS_API/abis/current"
# => { "FinancingMarket": [...], "FinancingMarketAdapter": [...], "ERC20": [...] }
```

The map is keyed by contract name and matches the current tx-engine version. Use it to encode calldata for writes (`requestFinancing`, `receiveFinancing`, `repay`, adapter `deposit`, …).

***

### Unit conventions

When moving between the API and contracts, remember:

* **Amounts** — API values are normalized decimals; contracts expect raw uint256. `parseUnits(value, assetToken.decimals)`.
* **Rates** — API is annualized APR (decimal); contracts use per-second `1e18`. `maxRate = floor(aprFraction * 1e18 / 31_536_000)`.
* **Durations** — API is milliseconds; contract `duration` is seconds.
* **Timestamps** — API is milliseconds; on-chain is seconds.

***

### MCP <a href="#mcp" id="mcp"></a>

Arenas ships a **Model Context Protocol** server at **`mcp.atomica.org`** — agent-native access to the same domain knowledge used to build the app. Point any MCP-capable client (Claude Code, Cursor, etc.) at it:

```jsonc
// .mcp.json
{
  "mcpServers": {
    "atomica": { "type": "http", "url": "https://mcp.atomica.org/mcp" }
  }
}
```

It exposes **skills** (end-to-end flow recipes), **primitives** (exact API endpoints and contract calls), **entity views**, **fixtures**, and **integration bundles** — so an agent can scaffold a borrower, LP, or approver flow from an authoritative source rather than guessing.

***

### Typed SDK

A typed SDK (calldata builders, unit conversion, and contract reads on top of the API and ABIs) is planned to sit above these surfaces. Until it ships, the recommended path is the **REST API + `abis/current` + a standard EVM library** (viem/ethers) for writes, with the **MCP** as the source of flow logic.

***

### CLI

For scripting and automation from a terminal or CI, see the [CLI](/build-with-arenas/cli).


# API Reference

The Arenas REST API returns **curated** JSON: amounts normalized by token decimals, rates annualized as decimal strings, and timestamps in **milliseconds**. It’s a read layer over the [Atomica](/atomica/atomica-protocol) contracts — writes are on-chain transactions your app sends with the wallet.

> Base URL and interactive schema: see your arena’s Swagger at `/swagger`. Examples below use `$ARENAS_API` for the base and `$ARENA_KEY` for your arena key.

***

### Authentication

Every endpoint is scoped to an arena via `arenaKey`, sent as a query parameter **or** a header:

| Method      | Example                                    |
| ----------- | ------------------------------------------ |
| Query param | `?arenaKey=$ARENA_KEY`                     |
| Header      | `X-Arena-Key: $ARENA_KEY` (or `Arena-Key`) |

Errors: **400** if the key is missing, **404** if no arena matches the key.

***

### Endpoints

| Method & path                               | Returns                                                                            |
| ------------------------------------------- | ---------------------------------------------------------------------------------- |
| `GET /lending/markets`                      | Financing markets, each with nested `requests[]`, `financings[]`, and `intents[]`. |
| `GET /lending/financings`                   | Flat list of financings (loans) for the arena.                                     |
| `GET /lending/pools`                        | Financing pools with typed market summaries.                                       |
| `GET /lending/pools/list/:account`          | An account’s pool balances, shares, and pending withdraw requests.                 |
| `GET /arena/access-tokens`                  | Access-token (NFT) contracts per chain — borrower eligibility.                     |
| `GET /networks`                             | Supported networks (chains with deployments).                                      |
| `GET /networks/deployments`                 | Deployment target catalog by chain.                                                |
| `GET /networks/native-token-rate`           | Native token USD spot price for a chain.                                           |
| `GET /abis/current`                         | Contract ABI map (`ContractName → abi[]`) for the current tx-engine version.       |
| `GET /provisioning-sync/last-synced-blocks` | Indexer progress — poll after writes before refetching.                            |

***

### Response conventions

* **Amounts** — decimal strings normalized by `assetToken.decimals` (e.g. `"1000"`), not raw uint256. Denormalize before sending to a contract.
* **Rates** — annualized decimal strings (e.g. `"0.15"` = 15% APR), converted from the on-chain per-second `1e18` rate.
* **Timestamps** — Unix **milliseconds** (`createdAt`, `earliestReceiveTs`, `deadlineTs`, …). Compare directly to `Date.now()`.
* **IDs** — composite where useful, e.g. request `id` = `{marketAddress}-{requestId}`, financing `id` = `{marketAddress}-{financingId}`.

***

### Enums

**Request `status`** (`requests[].status`):

| Value | Meaning   |
| ----- | --------- |
| 0     | REQUESTED |
| 1     | APPROVED  |
| 2     | DECLINED  |
| 3     | CLOSED    |
| 4     | FILLED    |
| 5     | EXPIRED   |

**Request `financingType`**: `0` INTEREST\_ACCRUAL · `1` FIXED\_REPAYMENT.

**Financing `status`**: `ACTIVE` · `REPAID` · `LIQUIDATED`. **Financing `financingType`**: `STANDARD` (accrual) · `LIQUIDITY_POOL` (fixed).

***

### Example

```bash
curl -s -H "X-Arena-Key: $ARENA_KEY" "$ARENAS_API/lending/markets" | jq '.[0] | {id, marketName, chainId, asset: .assetToken.symbol, requests: (.requests|length), intents: (.intents|length)}'
```

```jsonc
{
  "id": "0x6461...d467",         // market contract address (call target for writes)
  "marketName": "Brazil – Coffee – USDC",
  "chainId": 8453,
  "asset": "USDC",
  "requests": 3,
  "intents": 5
}
```

***

### Writing (transactions)

The API does not submit transactions. To perform a write:

1. Read the entity (market, request, pool) from the API.
2. Fetch ABIs from `GET /abis/current`.
3. Denormalize amounts and build calldata for the relevant [FinancingMarket](/atomica/financing-request-lifecycle) or pool-adapter function.
4. Have the user’s wallet sign and send it.
5. Poll `GET /provisioning-sync/last-synced-blocks` until the tx block is indexed, then refetch.

The per-role write flows are covered in [Embed Credit](/build-with-arenas/embed), [Launch a Market](/build-with-arenas/launch-market), and [Fund Markets](/build-with-arenas/fund-markets).