Partner Integration
How a partner page lets its users deposit into and redeem from Mulle vaults with the Mulle SDK, and how those deposits count toward the partner's revenue share. Last updated 2026-11-11.
Upcoming release
This page describes the integration as it will work after the next contract upgrade and SDK release. The package is not published on npm yet, and names can still change before release. Mulle will confirm the final version with each partner before the testnet upgrade.
Overview
Each partner has its own wrapped share token for each tranche on each chain. It is an ERC-20 token that wraps the tranche share 1:1, so its price follows the tranche share price. A user of the partner page deposits and redeems through the token contract and holds the wrapped share token instead of the tranche share.
- Deposit: the user's USDC goes through the wrapped share token into the vault. The deposit needs an attestation signed for the partner (see Attestations).
- Claim: after the deposit is settled, the user receives wrapped share tokens.
- Redeem: the user returns wrapped share tokens through the same contract and later claims USDC from it. The redemption request needs a redeem attestation, which the page gets from the Mulle API (see Redeem).
- The partner's revenue share is calculated from the total supply of its tokens (see Fees).
Requests are asynchronous (ERC-7540): a deposit or redemption is requested, processed at the product's next settlement (the periodic round in which the product prices its shares and fills requests), and then claimed. The request is recorded under the user's own wallet address, so pending and claimable amounts are read per user as for any Mulle vault.
Before You Start
Mulle sets up the following with each partner.
| Item | Used by | Description |
|---|---|---|
| Public API key | Partner page | Identifies the partner to the Mulle API. Starts with pk_. Safe to ship in a browser |
| Secret API key | Partner backend | Exchanges a deposit ticket for a signed attestation. Never ship it to a browser |
| IP allowlist | Partner backend | Outbound IP addresses of the servers that call the Mulle API with the secret key |
| Partner wallet address | Contracts | Identifies the partner on-chain. The same on every chain |
| Fee recipient address | Contracts | Wallet that receives the partner's revenue share payouts |
| Wrapped share tokens | Contracts, SDK | Deployed by Mulle for each product, tranche and chain the partner offers |
Install
npm install @mulle-protocol/sdk viem
viem is a peer dependency (2.37.10 or later, below 3). The SDK runs in the browser and in Node.
Partner Page
Create the API client with the partner's public API key, load the product config, and create the SDK from it. With a partner config, deposit, receive and redeem go through the wrapped share token without any extra parameter.
import { Mulle, createMulleApi, MulleApiError } from '@mulle-protocol/sdk'
const api = createMulleApi({ base: 'https://api.mulle.io', partnerKey: 'YOUR_PUBLIC_API_KEY' })
const mulle = await Mulle.create({ productId, ...(await api.config(productId)) })
mulle.connect(window.ethereum)
// Sign-in: the session token is bound to your partner key and your products.
const { token } = await api.signIn(me, (message) =>
wallet.signMessage({ account: me, message }))
const account = await api.get(`/market/products/${productId}/account/${me}`, token)
Partner Backend
The backend exchanges a deposit ticket for an attestation. Call it from a server whose outbound IP address is on the partner's allowlist.
import { requestAttestation } from '@mulle-protocol/sdk'
const signed = await requestAttestation({
base: 'https://api.mulle.io',
secretKey: process.env.MULLE_SECRET_KEY,
ticket,
})
// return signed to the browser; it passes signed.data to mulle.deposit
Before returning an attestation, the backend applies the partner's own eligibility checks (for example KYC) to the user. The attestation states that the partner approves this wallet to deposit.
Deposit
- The page checks whether the deposit can go through.
- The page asks the Mulle API for a ticket, a short-lived token for this deposit.
- The partner backend exchanges the ticket for an attestation, a signature that approves this wallet to deposit.
- The page sends the deposit request with the attestation.
- After the product's settlement fills the request, the user claims and receives wrapped share tokens.
// 1. Pre-check. gate.blockedBy === null → enable the button
const gate = await mulle.depositGate(me, 'senior', { chainId, amount: '10', attested: true })
// 2–3. Ticket (browser) → attestation (your backend)
const entry = mulle.inner.product().tranches
.find((t) => t.chainId === chainId && t.type === 'Senior')
const { ticket } = await api.ticket({ productId, chainId, vault: entry.vault, investor: me })
const signed = await yourBackend.attestation(ticket)
// 4. Deposit request
await mulle.deposit('senior', '10', { chainId, attestation: signed.data })
// 5. After settlement: claim wrapped share tokens
await mulle.receive('senior', 'deposit', { chainId })
The attestation is signed for the tranche vault address (entry.vault), not for the wrapped share token.
Redeem
A redemption request needs a redeem attestation. The page gets it from the Mulle API with the partner's public API key. The partner backend is not called. The amount is in wrapped share tokens.
// Redeem attestation (browser)
const entry = mulle.inner.product().tranches
.find((t) => t.chainId === chainId && t.type === 'Senior')
const signed = await api.redeemAttestation({ productId, chainId, vault: entry.vault, investor: me })
// Redemption request: returns wrapped share tokens
await mulle.redeem('senior', '5', { chainId, attestation: signed.data })
// After settlement: claim USDC
await mulle.receive('senior', 'redeem', { chainId })
A redemption request without an attestation passes only for a wallet that is already on Mulle's allowlist. Claiming USDC needs no attestation.
A holder can also unwrap wrapped share tokens into tranche shares 1:1. Unwrapped shares no longer count toward the partner's revenue share.
Attestations
- An attestation is an EIP-712 typed-data signature passed in the deposit or redemption request. The vault's allowlist contract (InvestorGate) verifies it on-chain.
- There are two kinds. A deposit attestation passes only a deposit request, and a redeem attestation passes only a redemption request.
- Both are signed for the tranche vault address (
entry.vault) and the user's wallet address, not for the wrapped share token. - An attestation is valid for 15 minutes. There is one per partner, chain, vault and wallet; asking again while it is unused returns the same one.
depositandredeemcheck the attestation (vault, wallet, kind, expiry) before any approval and throwATTESTATION_INVALIDif the gate would reject it. Request a new one.- Attach an attestation to every deposit and redemption request made through the partner page. A request without one passes only for a wallet that is already on Mulle's allowlist.
- Claims need no attestation.
Errors
There are two kinds of error, and their codes are written differently. Mulle API calls throw MulleApiError with the HTTP e.status and the API's e.code in lower case. Wallet and contract actions throw MulleError with an SDK e.code in upper case.
Mulle API errors (MulleApiError)
e.code | Meaning |
|---|---|
restricted_region | Not available in the user's region |
sanctioned | The address is sanctioned |
bad_ticket | The ticket expired or is invalid. Get a new one |
rate_limited | Too many requests. Retry later |
network_error | The API could not be reached (status 0) |
SDK errors (MulleError)
e.code | Meaning |
|---|---|
ATTESTATION_INVALID | The attestation would be rejected by the gate. Request a new one |
Backend setup errors
The backend's requestAttestation can also get bad_secret (unknown secret key), ip_not_allowed (the request did not come from an allowlisted IP), ticket_partner_mismatch (the ticket was issued under another partner's public key) and product_not_allowed. These are setup errors to fix on the partner side, not user messages.
Contract Functions
The SDK calls these functions. A partner that integrates without the SDK calls them directly.
The wrapped share token is an ERC-7540 vault with the same functions as a Mulle tranche vault: its asset is USDC and its share is the wrapped share token itself. An integration written for a tranche vault works by using the wrapped share token address instead. Deposit, claim, redemption and USDC claim all happen on this one contract.
Wrapped share token
| Function | Description |
|---|---|
requestDeposit(uint256 assets, address controller, address owner, bytes data) | Takes USDC from owner and requests a deposit for controller. data is the attestation. owner approves USDC to the token contract first |
requestDeposit(uint256 assets, address controller, address owner) | The standard ERC-7540 form, without an attestation. It passes only when controller is already on Mulle's allowlist. The deposit still mints wrapped share tokens and counts toward the partner |
deposit(uint256 assets, address receiver, address controller)mint(uint256 shares, address receiver, address controller) | Claims a filled deposit of controller and mints wrapped share tokens to receiver |
requestRedeem(uint256 shares, address controller, address owner, bytes data) | Burns wrapped share tokens of owner and requests redemption for controller. data is the redeem attestation, signed for controller |
requestRedeem(uint256 shares, address controller, address owner) | The standard ERC-7540 form, without an attestation. It passes only when controller is already on Mulle's allowlist |
redeem(uint256 shares, address receiver, address controller)withdraw(uint256 assets, address receiver, address controller) | Claims the USDC of a filled redemption of controller and sends it to receiver |
pendingDepositRequest, claimableDepositRequest | A user's deposit waiting for settlement, and the amount ready to claim |
pendingRedeemRequest, claimableRedeemRequest | A user's redemption waiting for settlement, and the amount ready to claim |
wrap(uint256 amount, address to) | Takes the caller's tranche shares and mints the same number of wrapped share tokens to to. Anyone can call it |
unwrap(uint256 amount, address to) | Burns the caller's wrapped share tokens and sends the same number of tranche shares to to. Anyone can call it |
In every request and claim function the caller must be the controller (and owner) itself or an operator it has approved, as in ERC-7540. A user normally passes their own wallet address for all of them.
Wrapped share token addresses are published per partner when the tokens are deployed. The request cycle is described in the Protocol reference.