> For the complete documentation index, see [llms.txt](https://docs.arenas.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.arenas.fi/build-with-arenas/api-reference.md).

# 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.md) 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.md) 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.md), [Launch a Market](/build-with-arenas/launch-market.md), and [Fund Markets](/build-with-arenas/fund-markets.md).