> ## Documentation Index
> Fetch the complete documentation index at: https://docs.multiliquid.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Delegates

> List your organization's stablecoin delegates on Ethereum, read each one's on-chain configuration, and prepare the transactions that change it.

A stablecoin delegate is the contract that holds your side of every swap you fill on Ethereum. Its delegate ID is your capital provider `id` in every swap and batch order route. [Stablecoin delegates](https://docs.multiliquid.xyz/evm/contracts/stablecoin-delegate.md) describes the contract, and [Administer your delegate](https://docs.multiliquid.xyz/api-reference/capital-providers/administer-delegate.md) shows how to change its configuration through the API.

On Ethereum mainnet, Multiliquid assigns delegates to your organization; on `evm-sepolia`, an admin can also deploy them in the Multiliquid app. An admin names deployed delegates and turns batch orders on or off for each in the app. A deployed delegate starts with batch orders off, and until they are first turned on it is not a batch order capital provider: the capacity and operator routes answer `404` with `NOT_FOUND`, and preparation answers `UNKNOWN_CAPITAL_PROVIDER`. When they are turned off later, the delegate is absent from the batch order listings, new orders and capacity updates are rejected with `BATCH_ORDERS_DISABLED`, operator selection and clearing still apply, and accepted orders keep their release, payloads, reports, and outcomes.

## Your organization ID

The delegate list takes your organization's ID. `GET /v1/organization` returns the organization the credential acts for, its `id` and `name`, and no other. It takes any API key, personal or organization, of any scope, or an account session with a selected organization, and no parameters.

```bash theme={null}
curl "https://api.multiliquid.xyz/v1/organization" \
  -H "Authorization: Bearer $MULTILIQUID_API_KEY"
```

```json Response theme={null}
{
  "id": "0f6b8a2c-3d4e-4f5a-8b9c-1d2e3f4a5b6c",
  "name": "Uniform Labs"
}
```

The response carries `Cache-Control: no-store`, and no rate-limit headers.

| Status | Code | When |
| - | - | - |
| `400` | `INVALID_REQUEST` | Any query parameter: the route takes none |
| `401` | `UNAUTHORIZED` | No credential, or one that is invalid, expired, or revoked. The response carries `WWW-Authenticate: Bearer`. |
| `403` | `ORGANIZATION_NOT_SELECTED` | An account session that selects no organization |
| `403` | `FORBIDDEN` | The credential no longer has access to its organization |
| `429` | `RATE_LIMITED` | The credential's user or organization allowance is spent |
| `503` | `SERVICE_UNAVAILABLE` | Access cannot be checked now; retry later |

## Listing your delegates

`GET /v1/organizations/{organizationId}/delegates?network=evm-mainnet` lists every delegate your organization owns on the network, ordered by delegate ID: committed assignments and completed deployments. It takes an account session of any member, or an API key of the organization with `read`, and serves `evm-mainnet` and `evm-sepolia`. Another organization in the path is a `404`.

```bash theme={null}
curl "https://api.multiliquid.xyz/v1/organizations/$ORGANIZATION_ID/delegates?network=evm-mainnet" \
  -H "Authorization: Bearer $MULTILIQUID_API_KEY"
```

Set `$ORGANIZATION_ID` to the `id` above. The response holds `delegates`, the whole list on one page, with no `nextCursor`. Each has:

| Field | Description |
| - | - |
| `delegateId` | The delegate's ID, your capital provider `id` |
| `delegateAddress` | The delegate contract, in EIP-55 mixed case; compare it case-insensitively with a capital provider's lowercase `address` |
| `swapContract` | The swap contract the delegate is registered with, in EIP-55 mixed case |
| `name` | The delegate's display name; `null` when none is set or the delegate is a committed assignment |
| `status` | `swappable` while the delegate has both custody addresses set, at least one asset whitelisted, is unpaused, and has its ID registered to it on the current swap contract, as Multiliquid last observed on-chain; `notSwappable` otherwise |
| `batchOrdersEnabled` | Whether batch orders are on for the delegate |
| `deploymentId` | The deployment that created the delegate; `null` for a committed assignment |

A deployed delegate whose stablecoin Multiliquid no longer lists stays in the list as `notSwappable`, and takes no swaps or orders.

| Status | Code | When |
| - | - | - |
| `400` | `INVALID_REQUEST` | An `organizationId` that is not a UUID, or a missing, unknown, or non-Ethereum `network` |
| `401` | `UNAUTHORIZED` | No credential, or one that is invalid, expired, or revoked. The response carries `WWW-Authenticate: Bearer`. |
| `403` | `INSUFFICIENT_SCOPE` | The API key lacks `read` |
| `403` | `ORGANIZATION_NOT_SELECTED` | An account session that selects no organization |
| `403` | `FORBIDDEN` | The credential no longer has access to its organization |
| `404` | `NOT_FOUND` | Another organization's ID in the path |
| `429` | `RATE_LIMITED` | The credential's user or organization allowance is spent |
| `503` | `SERVICE_UNAVAILABLE` | Access cannot be checked, or storage is unavailable; retry later |

## Admin state

`GET /v1/organizations/{organizationId}/delegates/{delegateId}/admin/state?network=evm-mainnet` reads a delegate's configuration as it is on-chain now. It takes an account session of any member, or an API key of the organization with `read`, and serves `evm-mainnet` and `evm-sepolia`, by those keys only. `delegateId` is the delegate's ID, a `0x`-prefixed 32-byte hex string. [Administer your delegate](https://docs.multiliquid.xyz/api-reference/capital-providers/administer-delegate.md#1-read-the-current-configuration) shows a request and its response, which carries `Cache-Control: no-store`.

Four optional query parameters each check one address, and add the matching field to the response:

| Parameter | Adds | Which is `true` when |
| - | - | - |
| `rwa` | `rwaWhitelisted` | The delegate accepts the RWA at this token address |
| `stablecoin` | `stablecoinWhitelisted` | The delegate accepts the counterparty stablecoin at this token address |
| `account` | `accountBlacklisted` | The delegate blocks this address as a user or receiver |
| `issuerAdminAddress` | `isIssuerAdmin` | This address is a capital provider admin of the delegate |

The response has:

| Field | Description |
| - | - |
| `delegateId` | The delegate's ID, your capital provider `id` |
| `delegateAddress` | The delegate contract |
| `network` | The network key you sent |
| `chainId` | The network's chain ID |
| `stablecoinAddress` | The stablecoin the delegate holds and pays out |
| `swapContract` | The swap contract the delegate settles for |
| `paused` | Whether settlement through the delegate is paused, by its capital provider admin or by Multiliquid |
| `rwaCustodyAddress` | The wallet that holds the delegate's RWAs; `null` when none is set |
| `stablecoinCustodyAddress` | The wallet that holds the delegate's stablecoin; `null` when none is set |
| `rwaColdStorageAddresses` | The RWA reserve wallets the delegate discloses, possibly empty; `null` when the delegate keeps no such list |
| `stablecoinColdStorageAddresses` | The stablecoin reserve wallets the delegate discloses, possibly empty; `null` when the delegate keeps no such list |
| `rwaWhitelisted`, `stablecoinWhitelisted`, `accountBlacklisted`, `isIssuerAdmin` | Present only when you send the matching query parameter, as above |

Every address is lowercase hex. Every value comes from the same block. Fee and discount rates are not part of the admin state.

| Status | Code | When |
| - | - | - |
| `400` | `INVALID_REQUEST` | An `organizationId` that is not a UUID, a `delegateId` that is not 32 bytes of hex, a missing or unknown `network` or one other than `evm-mainnet` and `evm-sepolia`, an optional parameter that is not an address, or an unknown parameter |
| `401` | `UNAUTHORIZED` | No credential, or one that is invalid, expired, or revoked. The response carries `WWW-Authenticate: Bearer`. |
| `403` | `INSUFFICIENT_SCOPE` | The API key lacks `read` |
| `403` | `ORGANIZATION_NOT_SELECTED` | An account session that selects no organization |
| `403` | `FORBIDDEN` | The credential no longer has access to its organization |
| `404` | `NOT_FOUND` | Another organization's ID in the path, or a delegate your organization does not own on the network |
| `429` | `RATE_LIMITED` | The credential's user or organization allowance is spent |
| `503` | `NETWORK_NOT_ACTIVE` | The API does not serve delegate administration on the network. `details`: `network`. |
| `503` | `SERVICE_UNAVAILABLE` | Access cannot be checked, or the chain cannot be read now; retry later |

## Preparing an admin action

`POST /v1/organizations/{organizationId}/delegates/{delegateId}/admin/prepare` returns the unsigned transaction that makes one change to a delegate, with checks of whether it would succeed now. It takes an account session of an admin, or an API key of the organization with `cp:admin`, and serves `evm-mainnet` and `evm-sepolia`, by those keys only. The body is at most 1 KiB. [Administer your delegate](https://docs.multiliquid.xyz/api-reference/capital-providers/administer-delegate.md#2-prepare-the-change) shows a request and its responses, which carry `Cache-Control: no-store`.

Preparing stores nothing and changes nothing on-chain. Your capital provider admin wallet signs the transaction and sends it to the network; Multiliquid never signs or sends it.

The body has:

| Field | Description |
| - | - |
| `network` | `evm-mainnet` or `evm-sepolia` |
| `issuerAdminAddress` | The capital provider admin wallet that will sign and send the transaction. On-chain, the delegate keeps its admins under the identifier `issuerAdmins`. |
| `action` | The change, an object whose `type` selects one of the [admin actions](#admin-actions), with that action's fields |

### Admin actions

Every address is a nonzero Ethereum address. A rate is `rateBps`, a whole number of basis points below `10000` (100%): `10` is 0.1%, and `1` is 1 basis point. An RWA ID or stablecoin ID is a `0x`-prefixed 32-byte hex string, as [deployment info](https://docs.multiliquid.xyz/api-reference/data/endpoints.md#deployment-info) lists. [Stablecoin delegates](https://docs.multiliquid.xyz/evm/contracts/stablecoin-delegate.md#capital-provider-administration) describes the effect of each change on-chain.

| `type` | Fields | What it does |
| - | - | - |
| `whitelistRwa` | `rwa`, `accepted` | Accepts the RWA at the token address `rwa` when `accepted` is `true`, and stops accepting it when `false` |
| `setRwaDiscountRate` | `rwaId`, `rateBps` | Sets the discount on the incoming RWA |
| `setRwaRedemptionFee` | `rwaId`, `rateBps` | Sets the fee on the outgoing RWA |
| `whitelistStablecoin` | `stablecoin`, `accepted` | Accepts the counterparty stablecoin at the token address `stablecoin` when `accepted` is `true`, and stops accepting it when `false` |
| `setStablecoinAcceptanceFee` | `stablecoin`, `rateBps` | Sets the fee for accepting the counterparty stablecoin |
| `setStablecoinRedemptionFee` | `stablecoin`, `rateBps` | Sets the fee for paying out the counterparty stablecoin |
| `setAutoLiquidityStablecoinId` | `autoLiquidityStablecoinId` | Selects the stablecoin ID [auto-sweep](https://docs.multiliquid.xyz/evm/guides/auto-sweep.md) uses, or 32 zero bytes to turn auto-sweep off |
| `setRwaCustodyAddress` | `custodyAddress` | Sets the wallet that holds the delegate's RWAs. It cannot be the delegate itself. |
| `setStablecoinCustodyAddress` | `custodyAddress` | Sets the wallet that holds the delegate's stablecoin. It cannot be the delegate itself. |
| `addRwaColdStorageAddress`, `removeRwaColdStorageAddress` | `coldStorageAddress` | Lists or delists an RWA reserve wallet, for disclosure only. It cannot be the delegate itself. |
| `addStablecoinColdStorageAddress`, `removeStablecoinColdStorageAddress` | `coldStorageAddress` | Lists or delists a stablecoin reserve wallet, for disclosure only. It cannot be the delegate itself. |
| `setBlacklist` | `account`, `blacklisted` | Blocks `account` as a user or receiver of the delegate when `blacklisted` is `true`, and unblocks it when `false` |
| `withdrawStablecoin` | `to`, `amount` | Sends `amount` of the stablecoin that the delegate contract itself holds to `to`. `amount` is in whole tokens of the delegate's stablecoin, as a nonzero decimal string with at most 6 decimal places and no more than the stablecoin has, such as `"1500.25"` |
| `pause` | None | Pauses settlement through the delegate |
| `unpause` | None | Unpauses settlement through the delegate |
| `addIssuerAdmin` | `issuerAdminAddress` | Adds a capital provider admin |
| `removeIssuerAdmin` | `issuerAdminAddress` | Removes a capital provider admin other than the body's `issuerAdminAddress`, since an admin cannot remove itself |

For example, a delegate is paused with `{"type": "pause"}`, and a custody address is set with `{"type": "setStablecoinCustodyAddress", "custodyAddress": "0x…"}`.

### Prepare response

| Field | Description |
| - | - |
| `delegateId` | The delegate's ID |
| `delegateAddress` | The delegate contract, which the transaction calls |
| `network` | The network key you sent |
| `description` | One sentence that describes the change, to show before signing, such as `Set discount rate to 10 bps for RWA 0x… on delegate 0x…` or `Withdraw 1500.25 USDC to 0x… on delegate 0x…` |
| `checks.isIssuerAdmin` | Whether `issuerAdminAddress` is a capital provider admin of the delegate now |
| `checks.simulation.passed` | Whether the transaction succeeds against the current chain state |
| `checks.simulation.error` | Present when the simulation fails: why, such as the contract error it reverts with, or that it runs out of gas |
| `transaction` | The complete transaction to sign, in the form of a [swap build's](https://docs.multiliquid.xyz/api-reference/swap/quote-and-build.md#transactions-on-evm): `runtime` (`evm`), `chainId`, `from` (`issuerAdminAddress`), `to` (the delegate), `data`, `value` (always `"0"`), `nonce`, `gas`, `maxFeePerGas`, `maxPriorityFeePerGas`, and `serialized`, the bytes to sign. `gas` and `serialized` are `null` when the simulation fails. Sign it as returned; the wallet sets no nonce or fees of its own. |

A failing check never fails the request; it answers `200` with the check failing, so you can see what to fix. Don't send a transaction whose checks fail: it reverts on-chain.

| Status | Code | When |
| - | - | - |
| `400` | `INVALID_REQUEST` | An `organizationId` that is not a UUID, a `delegateId` that is not 32 bytes of hex, a body that is not JSON, or a missing JSON content type |
| `401` | `UNAUTHORIZED` | No credential, or one that is invalid, expired, or revoked. The response carries `WWW-Authenticate: Bearer`. |
| `403` | `INSUFFICIENT_SCOPE` | The API key lacks `cp:admin` |
| `403` | `FORBIDDEN` | An account session of a member who is not an admin, or a credential that no longer has access to its organization |
| `403` | `ORGANIZATION_NOT_SELECTED` | An account session that selects no organization |
| `404` | `NOT_FOUND` | Another organization's ID in the path, or a delegate your organization does not own on the network |
| `413` | `PAYLOAD_TOO_LARGE` | A body over 1 KiB |
| `422` | `INVALID_BODY` | A missing, unknown, or invalid field: a `network` other than `evm-mainnet` and `evm-sepolia`, an unknown action `type`, a zero or malformed address or ID, a `rateBps` that is not a whole number below `10000`, a withdrawal `amount` that is zero, is not a decimal string, or has more than 6 decimal places or more than the stablecoin has, a custody or cold storage address that is the delegate, or a `removeIssuerAdmin` that names the body's `issuerAdminAddress`. `details.field` names it. |
| `429` | `RATE_LIMITED` | The credential's user or organization allowance is spent |
| `503` | `NETWORK_NOT_ACTIVE` | The API does not serve delegate administration on the network. `details`: `network`. |
| `503` | `SERVICE_UNAVAILABLE` | Access cannot be checked, or the chain cannot be read or simulated now; retry later |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.