Skip to content

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.

User
User wallet
on the partner page
Partner
Wrapped share token
one per tranche per chain
Mulle
Tranche vault
Senior or Junior
  • 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.

ItemUsed byDescription
Public API keyPartner pageIdentifies the partner to the Mulle API. Starts with pk_. Safe to ship in a browser
Secret API keyPartner backendExchanges a deposit ticket for a signed attestation. Never ship it to a browser
IP allowlistPartner backendOutbound IP addresses of the servers that call the Mulle API with the secret key
Partner wallet addressContractsIdentifies the partner on-chain. The same on every chain
Fee recipient addressContractsWallet that receives the partner's revenue share payouts
Wrapped share tokensContracts, SDKDeployed 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

  1. The page checks whether the deposit can go through.
  2. The page asks the Mulle API for a ticket, a short-lived token for this deposit.
  3. The partner backend exchanges the ticket for an attestation, a signature that approves this wallet to deposit.
  4. The page sends the deposit request with the attestation.
  5. 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.
  • deposit and redeem check the attestation (vault, wallet, kind, expiry) before any approval and throw ATTESTATION_INVALID if 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.codeMeaning
restricted_regionNot available in the user's region
sanctionedThe address is sanctioned
bad_ticketThe ticket expired or is invalid. Get a new one
rate_limitedToo many requests. Retry later
network_errorThe API could not be reached (status 0)

SDK errors (MulleError)

e.codeMeaning
ATTESTATION_INVALIDThe 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

FunctionDescription
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, claimableDepositRequestA user's deposit waiting for settlement, and the amount ready to claim
pendingRedeemRequest, claimableRedeemRequestA 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.