# Lending

> Coming soon, upon request — this feature is turned on for your tenant by the Aurea team. [Contact us](https://www.aureahub.com/contact)

Let your users earn a variable rate on their euro stablecoin (EUR.e): supply it to a lending pool from their wallet, watch the position grow, and withdraw it — part or all, interest included — back to the same wallet.

## Overview

- **Direct routes.** The routes under `/v1/lending` read the user's position, supply and withdraw. A custodial wallet is signed by Aurea in one call; a client-side or MPC wallet prepares the transactions, signs them on the device and sends the signatures back.
- **The same lending as an Earn product.** [Earn](https://docs.aureahub.com/docs/guide-earn.md) offers this lending as the product `lumen`, with a disclosure the user accepts, quotes, exact approvals and an operation record for each deposit or withdrawal. The two are separate switches of your tenant.
- **Amounts** are integer strings in EUR.e's smallest unit, 18 decimals (`"1000000000000000000"` is 1 EUR.e; [Amount Units](https://docs.aureahub.com/docs/amounts.md)).
- **A position** is the user's balance in the pool: what they supplied plus the interest it earned, both together.

## Coming soon, upon request

[Coming soon, upon request](https://docs.aureahub.com/docs/feature-availability.md) Lending is turned on per tenant: [Get Your Tenant](https://docs.aureahub.com/docs/tenant-info.md) answers `configuration.lumenEnabled` `true`. Until then every lending route answers `403` (`Lumen is not enabled for this tenant.` …). Aurea sets up the chains lending runs on; with none on a network, Positions answers an empty result, Rate History an empty `history`, and the other routes `404`.

## Calling the Lending Routes

- Every lending route needs **both** the user's access token (`Authorization: Bearer …`) and your tenant's request signature, or a server token instead ([Authentication](https://docs.aureahub.com/docs/authentication.md), [Server Credentials](https://docs.aureahub.com/docs/guide-server-credentials.md)). Call them from your server, on the user's behalf.
- They are for the roles that sign: `user`, `owner`, `tenantadmin` and `signer` ([Roles](https://docs.aureahub.com/docs/authentication.md)), and act on that user's wallets.
- `isTestnet` picks the network: `true` testnet, `false` mainnet.
- The supply, withdrawal, preparation and broadcast routes allow 5 requests a minute.

## Chain and Wallet

No route takes a chain or a wallet: Aurea picks them, the same way every time.

- **The wallets:** the user's EVM wallets on the network (Solana wallets are left out). A custodial supply or withdrawal uses only those whose key the platform holds for your tenant.
- **The chain:** among the lending chains the user has a wallet on, the first of Gnosis Chain (100), Chiado (10200), Polygon (137), Mumbai (80001), Ethereum (1) and Sepolia (11155111), then the lowest chain id; with no wallet on any, the first lending chain in that order.
- **The wallet:** the user's wallet on that chain, or else their first EVM wallet — an EVM address is the same on every EVM chain.

## Positions and Rates

- [Positions](https://docs.aureahub.com/docs/lending-positions.md) answers, for each lending chain, the position of the user's first EVM wallet (`depositedWei`) and the pool's current yearly rate (`apy`, in percent, compounded), and what the wallet still holds (`walletBalanceWei`).
- [Rate History](https://docs.aureahub.com/docs/lending-rate-history.md) answers the rate over the last 90 days, one point every 3 days, for a chart.

## Custodial Wallets

1. [Supply](https://docs.aureahub.com/docs/lending-supply.md) with `weiAmount`: Aurea approves the pool to take the token when the wallet's allowance falls short, supplies, waits for the receipt and answers its `txHash`.
2. [Withdraw](https://docs.aureahub.com/docs/lending-withdraw.md) with `weiAmount`, or `"max"` for the whole position with its interest: the token returns to the same wallet.
3. Both take an optional `Idempotency-Key`; a tenant on the institutional security profile needs one, and its policy can hold the operation for approval (`202`, [Approvals](https://docs.aureahub.com/docs/guide-approvals.md)).

## Client-Side and MPC Wallets

1. [Prepare a Supply](https://docs.aureahub.com/docs/lending-prepare-supply.md) or [Prepare a Withdrawal](https://docs.aureahub.com/docs/lending-prepare-withdraw.md) answers `steps` — unsigned EIP-1559 transactions, an approval first when one is needed — and the `walletAddress` to sign with.
2. Sign each step's `txHashToSign` with that wallet — the device key, or the MPC signing ceremony — as a raw hash, with no message prefix. Each signature is `{ "v", "r", "s" }`, `v` the y-parity `0x0` or `0x1` ([Signing Primitives](https://docs.aureahub.com/docs/signing.md)).
3. [Send the Signatures](https://docs.aureahub.com/docs/lending-broadcast.md) with the `steps`, unchanged, and the `signatures` in the same order. Aurea checks that every step was signed by the user's wallet, sends them one after the other, waits for each receipt, and answers the last `txHash`.

Send the signatures soon: the steps carry the wallet's nonce and the fees of the moment they were prepared.

## Approvals of the Token

A supply needs the pool approved to take the token. When the wallet's allowance does not cover the amount, the approval is for an unlimited amount, so later supplies need none — except for a tenant whose exact approvals are enforced [Coming soon, upon request](https://docs.aureahub.com/docs/feature-availability.md): then the approval is of exactly the amount, and any allowance left after the supply is set back to zero ([Signing Rules](https://docs.aureahub.com/docs/guide-signing-rules.md)).

## Errors

| Status | When |
| --- | --- |
| 400 | A field is missing or not as described; the user has no EVM wallet, or — for a custodial supply or withdrawal — none whose key the platform holds for your tenant (use the preparation routes); a broadcast with no steps, or with as many signatures as steps not; the chain refused a step (not enough gas, a nonce already used, the transaction reverted). |
| 403 | Lending is not on for your tenant; the role does not sign; a policy rule refuses it, or asks for an approval on a preparation (`POLICY_APPROVAL_REQUIRED`). |
| 404 | No lending chain is set up on the network. |
| 422 | A broadcast signature that cannot be read, or that is not the user's wallet's. |
| 423 | A freeze stops the user, the wallet or your tenant from signing ([Freezes & Quarantines](https://docs.aureahub.com/docs/guide-freezes.md)). |

---

Web version: https://docs.aureahub.com/#guide-lending