# About Tesseract
> **Not for UK persons.** This website and its contents are not directed at persons located in, or resident in, the United Kingdom. They do not constitute a financial promotion within the meaning of section 21 of the Financial Services and Markets Act 2000, and are not approved by an authorised person. Access is granted on the basis that the accessing person is not a UK person and will not disseminate the contents to any UK person.
### What do we do?
Many people who hold crypto assets cannot generate yield on them. The rails to access yield are underdeveloped within crypto, and many avenues that exist today lack sufficient oversight or require advanced financial and technological knowledge.
**Tesseract Investment Oy** provides discretionary portfolio management of crypto-assets under MiCA, executed through per-client on-chain vaults. Alongside that regulated service, Tesseract Earn Oy and its UK Special Purpose Vehicles offer institutional lending outside the MiCA perimeter, applying equivalent compliance and risk standards.
We deliver these services either by partnering with institutions such as crypto exchanges, custodians, and fintechs who offer them to their end customers, or directly to institutional counterparties via direct wallet connectivity.
### Who we are
Founded in 2017, we are a combination of traditional finance and technology experts who want to help elevate the crypto industry to be a true alternative to existing traditional finance.
**Tesseract Investment Oy** is MiCA-authorised and FIN-FSA-supervised as a Crypto Asset Service Provider. In Dedicated Client Vault contexts, the service operates within the custody, portfolio management, and transfer services limbs of that authorisation; the full authorisation also covers investment advice and reception / transmission of orders.
Our technology platform, **Tesseract Earn Oy**, is certified to ISO/IEC 27001:2022 (valid to October 2027, audited by Prescient Security) and holds a SOC 2 Type II report (three consecutive years, audited by Prescient Security). The CASP operates on that certified platform. Reports are available on request under NDA.
Our headquarters are in Helsinki, Finland, with a global team of professionals delivering regulated, institutional-grade yield services to institutional clients, partners, and treasuries.
### Why partner with us?
We have operated the B2B2C yield model since 2017. Our value driver is trust and compliance supported by institutional-grade technology. We invest in rigorous risk management processes and operate with a high degree of transparency.
* **MiCA CASP authorisation (Tesseract Investment Oy)** — Discretionary portfolio management, custody, and transfer services for the DCV mandate
* **ISO 27001 & SOC 2 certified** — Security controls at the technology platform entity (Tesseract Earn Oy)
* **Per-client on-chain vault architecture** — Each client mandate is executed in a dedicated vault contract
* **Operating since 2017 with institutional partners**
***
### Service availability
Tesseract Investment Oy does not provide services to persons in the United States, the United Kingdom, the United Arab Emirates, Japan, South Korea, Singapore or Australia. Service availability in other jurisdictions is subject to Tesseract's assessment of applicable regulatory and sanctions requirements.
***
*This website is a marketing communication of Tesseract Investment Oy, a crypto-asset service provider authorised under Regulation (EU) 2023/1114 (MiCA) by the Finnish Financial Supervisory Authority (FIN-FSA). It is directed at institutional counterparties under a non-disclosure agreement with Tesseract. It is not an offer or solicitation.*
# Yield Offering
Tesseract provides two yield services: Dedicated Client Vaults (regulated portfolio management, Tesseract Investment Oy) and Institutional Lending (Tesseract Earn Oy and its UK SPVs, outside the MiCA
> **Not for UK persons.** This website and its contents are not directed at persons located in, or resident in, the United Kingdom. They do not constitute a financial promotion within the meaning of section 21 of the Financial Services and Markets Act 2000, and are not approved by an authorised person.
Tesseract provides two yield services: **Dedicated Client Vaults** (regulated portfolio management, Tesseract Investment Oy) and **Institutional Lending** (Tesseract Earn Oy and its UK SPVs, outside the MiCA perimeter).
### Dedicated Client Vaults
Tesseract Investment Oy delivers the DCV service as a discretionary portfolio management mandate executed through per-client on-chain vaults on Ethereum mainnet. Each client receives their own isolated vault. There is **no pooling and no commingling** of assets.
Yield is tracked through share price appreciation with auto-compounding — no manual claim required. Current strategy options are visible in the [Tesseract app](https://app.tesseract.fi).
| Parameter | Detail |
| ------------------------------ | -------------------------------------------------------------------------------- |
| Blockchain | Ethereum mainnet |
| Supported Assets | USDC, wETH, wBTC |
| Minimum Deposit | $50,000 USDC |
| Indicative Yield (Stablecoins) | \~5-6% (Conservative) / \~8-12% (Advanced) |
| Indicative Yield (ETH) | \~4-6% |
| Indicative Yield (BTC) | \~3-5% |
| Withdrawals | Instant for amounts covered by liquid balance; scheduled flow for larger amounts |
> ***Indicative yield footnote.** Indicative yields reflect gross annualised returns targeted for comparable DCV mandates over the twelve-month period ending 31 March 2026, before management and performance fees. Yields are variable, not a forecast and not a guarantee, and will differ between clients, strategies, and periods. Past performance is not indicative of future results. See the Risks section for the full set of risk factors.*
### Institutional Lending
Institutional Lending is provided by **Tesseract Earn Oy** and its UK Special Purpose Vehicles (Tesseract UK Access I Ltd and Tesseract UK Access II Ltd), outside the MiCA regulatory perimeter. Tesseract Earn Oy applies compliance standards equivalent to those applicable to Tesseract Investment Oy, including KYC on all borrowers, SPV-level asset segregation, and transparent portfolio reporting.
The service offers institutional counterparties a route to earn yield on digital assets through lending to vetted institutional borrowers. A delta-neutral strategy eliminates exposure to cryptocurrency price volatility, and the loan portfolio is diversified across multiple borrowers to mitigate concentration risk. Collateral is managed securely through a third-party custodian, and loan terms allow for up to 100% asset withdrawal without lock-up periods.
Tesseract provides regular monthly reports detailing loan performance and portfolio parameters. Risk management practices include rigorous credit assessments and AML/KYC compliance.
**Product Sheet:** [Lending Product Sheet](https://tesseract.fi/wp-content/uploads/01_Lending_1.0.pdf)
### Currency Support
**Dedicated Client Vaults — Tesseract Investment Oy, MiCA CASP**
Currency
Vaults
Bitcoin (BTC)
✅ (wBTC)
Ethereum (ETH)
✅
USDC
✅
**Institutional Lending — Tesseract Earn Oy / UK SPVs, outside the MiCA perimeter**
| Currency | Lending |
| -------------- | ------- |
| Bitcoin (BTC) | ✅ |
| Ethereum (ETH) | ✅ |
| USDC | ✅ |
| Litecoin | ✅ |
| Ripple (XRP) | ✅ |
| Solana | ✅ |
| Cardano | ✅ |
| Polygon | ✅ |
| Polkadot | ✅ |
| Binance Coin | ✅ |
| Avalanche | ✅ |
| Dogecoin | ✅ |
| DAI | ✅ |
| ATOM | ✅ |
| NEAR | ✅ |
| Kusama | ✅ |
| Others | ✅ |
* *We remain open to consider further assets according to market conditions*
***
> **Risks.** Discretionary portfolio management of crypto-assets involves significant risks, including smart contract risk, DeFi protocol risk, oracle risk, liquidity risk, market stress risk, counterparty risk, custody risk and regulatory change risk, and the risk of total loss of capital. Yields are indicative only, not guaranteed, and will vary.
***
*This website is a marketing communication of Tesseract Investment Oy, a crypto-asset service provider authorised under Regulation (EU) 2023/1114 (MiCA) by the Finnish Financial Supervisory Authority (FIN-FSA). It is directed at institutional counterparties under a non-disclosure agreement with Tesseract. It is not an offer or solicitation.*
# Platform Offering
Tesseract's platform delivers three integration models: Dedicated Client Vaults, Earn API, and Earn Direct.
> **Not for UK persons.** This website and its contents are not directed at persons located in, or resident in, the United Kingdom. They do not constitute a financial promotion within the meaning of section 21 of the Financial Services and Markets Act 2000, and are not approved by an authorised person.
### Dedicated Client Vaults
DCVs are institutional-grade, per-client on-chain vaults on Ethereum mainnet. Each client mandate is executed in a dedicated vault contract with no pooling or commingling of assets. The DCV service is delivered by **Tesseract Investment Oy** under its MiCA-authorised discretionary portfolio management mandate.
DCVs are suited to custodians, institutional investors, exchanges, and any counterparty seeking regulated, transparent, segregated yield generation on crypto-assets.
**Integration models:**
* **Tesseract app** — end clients access their vaults via [app.tesseract.fi](https://app.tesseract.fi) using WalletConnect (retail) or Narval (institutional).
* **Direct smart-contract integration** — partners interact with the vault contracts and the [Public API](https://api.vault.tesseract.fi/public/docs) from their own infrastructure. See the [DCV Integration Guide](/dedicated-client-vaults/integration-guide).
### Earn API
Earn API empowers businesses to offer crypto yield opportunities to their users without the burden of backend infrastructure. With seamless integration and built-in wallet, security, and compliance features, it enables platforms — such as exchanges and fintechs — to focus on user experience while maintaining control over identity verification.
It's ideal for companies entering the crypto yield space that want to provide a smooth and customizable experience.
**Earn API is the solution for you if:**
* You operate a platform and want to seamlessly integrate Earn functionality while maintaining an excellent user experience
* You are a regulated entity and manage your own KYC processes
* You have a capable tech team ready to handle the technical integration
**Estimated integration time:** 14–21 days
### Earn Direct
Earn Direct allows Tesseract to serve end-users directly, with Tesseract Investment Oy handling the entire KYC / AML and onboarding process. This model is suited to partners who prefer to refer their clients to a regulated provider rather than operate the regulatory infrastructure in-house, and to companies seeking regulated yield services on their treasury holdings.
**Tesseract Investment Oy** — MiCA-authorised and FIN-FSA-supervised as a Crypto Asset Service Provider — performs the KYC/AML, custody, and asset transfer functions. Users can connect their wallets through WalletConnect and deposit directly via our WebApp.
> **Note on custody architecture.** Earn Direct and DCV use different custody architectures. Earn Direct uses MiCA-authorised custody through Fireblocks MPC. DCV is non-custodial; the client's assets reside in their own dedicated vault contract.
**Earn Direct is the right integration model if:**
* You are a partner that does not hold the relevant regulatory authorisations in your jurisdiction, and you want to offer yield services to your clients by partnering with a regulated provider. Tesseract Investment Oy provides the regulated compliance and custody layer; you remain responsible for your own regulatory obligations, including any licensing, suitability and consumer-protection requirements applicable to you.
* You lack the technical resources to implement a direct Earn API integration.
**Estimated integration time:** 7 days
***
*This website is a marketing communication of Tesseract Investment Oy, a crypto-asset service provider authorised under Regulation (EU) 2023/1114 (MiCA) by the Finnish Financial Supervisory Authority (FIN-FSA). It is directed at institutional counterparties under a non-disclosure agreement with Tesseract. It is not an offer or solicitation.*
# Security & Compliance
**Tesseract Investment Oy** holds the regulatory authorisations and security certifications expected of an institutional yield provider.
### Licenses & certifications
* **MiCA CASP authorisation (Tesseract Investment Oy)** — The DCV service operates within the custody, portfolio management, and transfer services limbs of Tesseract Investment Oy's CASP authorisation. The full authorisation also covers investment advice and reception / transmission of orders. Certificate of registration available on request under NDA.
* **ISO/IEC 27001:2022 (Tesseract Earn Oy)** — valid to October 2027, audited by Prescient Security. Reports available on request under NDA.
* **SOC 2 Type II (Tesseract Earn Oy)** — three consecutive years, audited by Prescient Security. Reports available on request under NDA.
### Risk management
**Smart contract & protocol.** All vault contracts are audited before mainnet deployment. Only pre-approved, vetted DeFi protocols may be used; new protocol whitelisting and key-management changes require multisig approval. DeFi counterparties and institutional lending borrowers go through the same due-diligence process before onboarding.
**Operational.** 24/7 automated monitoring of positions, with auto-deleveraging when risk thresholds are breached. Vault execution is constrained to pre-approved interactions with whitelisted protocols. Under the Vault Services Agreement, Tesseract Investment Oy has the right to invoke an emergency freeze on vault operations in defined incident scenarios, exercisable only in accordance with the VSA and applicable law.
**Per-client isolation (DCVs).** Each vault is a standalone smart contract; one client's risk exposure cannot affect another's. Yield auto-compounds at the vault level. Withdrawals clear instantly from available liquidity or through the scheduled-withdrawal flow for larger amounts.
**Lending.** Delta-neutral strategy eliminates directional price exposure. Loans are diversified across vetted institutional borrowers and collateral is held with third-party custodians. Borrower creditworthiness is monitored on an ongoing basis.
**Regulatory.** Proactive dialogue with FIN-FSA on service developments. Implements Travel Rule obligations under Regulation (EU) 2023/1113 via Sumsub. AML / KYC via Sumsub with TRM for transaction monitoring.
**Transparency & reporting.** Vault state, transaction history, and performance time-series are exposed through the reporting API. Non-transferable share tokens provide cryptographic proof of client ownership verifiable on-chain without Tesseract's cooperation. Monthly performance reports are published for the Lending product.
### Audits
Each product is independently audited where applicable. Product-specific audit reports are linked from the relevant section — for DCVs, see [Audit Reports](/dedicated-client-vaults/reference/audit-reports).
***
> *Tesseract Investment Oy is authorised as a Crypto Asset Service Provider (CASP) under Regulation (EU) 2023/1114 (MiCA). On-chain yield vaults involve significant risks, including smart contract vulnerabilities, liquidity risk, and the risk of total loss of capital. Past performance is not indicative of future results.*
# Introduction
> **Not for UK persons.** This website and its contents are not directed at persons located in, or resident in, the United Kingdom. They do not constitute a financial promotion within the meaning of section 21 of the Financial Services and Markets Act 2000, and are not approved by an authorised person.
### What are Dedicated Client Vaults?
Tesseract's Dedicated Client Vaults (DCVs) are on-chain yield vaults where **each client gets their own isolated vault** on Ethereum mainnet. The structural innovation is simple: one vault per client, no pooling, no commingling. This is what enables the DCV to sit cleanly within the MiCA framework when most yield products in the market cannot.
**Product classification:** A MiCA-authorised discretionary portfolio management mandate operated by **Tesseract Investment Oy**, executed through per-client on-chain vaults. It is not software, not a fund, not a wrapper — it is regulated asset management.
### Why the design matters
The DCV architecture is designed around the principle that each client's assets should be held in a dedicated, on-chain vault they control for the lifetime of the mandate. That design choice sits at the heart of the compliance, tax and operational profile of the service. Clients are encouraged to obtain their own legal and tax advice.
### How it works
1. **One vault per client** — each client's vault is a standalone smart contract on Ethereum mainnet.
2. **Non-transferable share token** representing 100% ownership (ERC‑4626 compliant). Shares are non-transferable by design, which is intended to keep the DCV outside securities and collective-investment-scheme characterisation. Tesseract's legal analysis supporting this design is available to institutional counterparties under NDA.
3. **Tesseract Investment Oy manages each vault individually** under a MiCA-authorised discretionary mandate.
4. Each vault holds its own positions directly — the client remains the on-chain owner at all times.
5. **Yield is tracked through share price appreciation** — auto-compounding, no manual claim required.
6. **Strategy selection** — the client chooses a strategy at vault creation based on their risk profile, and can switch strategies on the fly as their preferences change. Current options are visible in the [Tesseract app](https://app.tesseract.fi).
### Key parameters
| Parameter | Detail |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| Blockchain | Ethereum mainnet |
| Supported assets | USDC, WETH, WBTC |
| Minimum deposit | $50,000 USDC (or equivalent in WETH/WBTC) |
| Withdrawals | Instant for amounts covered by liquid balance; scheduled flow for larger amounts (up to \~24h) |
| Wallet support | WalletConnect, Narval, Ledger, Coinbase Wallet, Safe and others |
| Reporting | On-chain state plus the [Public API](/dedicated-client-vaults/reference/public-api) |
Current per-asset minimums and fee configuration are always readable on-chain — see [Contract Methods](/dedicated-client-vaults/reference/contract-methods).
### Who it's for
* **Custodians** seeking to offer compliant yield to their clients
* **Institutional investors** requiring per-client asset segregation
* **Exchanges and neobanks** adding regulated yield products
* **Wallet providers** offering on-chain yield with full transparency
* **Crypto foundations and DAOs** managing treasury assets
> *Tesseract Investment Oy is authorised as a Crypto Asset Service Provider (CASP) under Regulation (EU) 2023/1114 (MiCA). On-chain yield vaults involve significant risks, including smart contract vulnerabilities, liquidity risk, and the risk of total loss of capital. Past performance is not indicative of future results.*
***
*This website is a marketing communication of Tesseract Investment Oy, a crypto-asset service provider authorised under Regulation (EU) 2023/1114 (MiCA) by the Finnish Financial Supervisory Authority (FIN-FSA). It is directed at institutional counterparties under a non-disclosure agreement with Tesseract. It is not an offer or solicitation.*
# Vault Lifecycle
End-to-end flow of a Dedicated Client Vault — from a wallet's first access through to reading vault state — organized around the four things an integrator needs to know: how a wallet gets access, how a vault comes into existence, how it operates, and how to interact with it day-to-day. For step-by-step code, see the [Integration Guide](/dedicated-client-vaults/integration-guide).
### 1. Wallet access — the Whitelisting contract
Before any wallet can deploy or operate a vault, it has to appear on Tesseract's on-chain `Whitelisting` contract with a non-expired entry.
To get there, the client completes the [Compliance & Onboarding](/dedicated-client-vaults/compliance-and-onboarding) flow — KYC/KYB, then proof-of-ownership signatures for the wallets they want to use (one or more can be added). Once checks clear, Tesseract writes each wallet to the `Whitelisting` contract on-chain. From that moment the wallets work unattended until their entry expires — shortly before expiry, Tesseract emails the client with instructions to complete KYC renewal; once the renewal is cleared, the new expiration is written back to the whitelist on-chain.
For partner-led onboarding (custodian model), the partner and Tesseract agree on compliance responsibilities and the partner's users are provisioned through the Compliance API — see [Scenario B](/dedicated-client-vaults/integration-guide/scenario-b). The end state is identical: each wallet carries an active on-chain whitelist entry.
There is one `Whitelisting` contract covering all assets. See [Contract Addresses](/dedicated-client-vaults/reference/contract-addresses).
### 2. Vault creation — the Vault Deployer
A dedicated vault is created in a single transaction against a **Vault Deployer**. There's one deployer per supported asset (USDC, WETH, WBTC) — the caller invokes the deployer for the asset they want to hold, passing an initial deposit and acceptable fee bounds.
Most clients drive this through the Tesseract app at [app.tesseract.fi](https://app.tesseract.fi) — connect a whitelisted wallet, pick the asset, enter the deposit amount, and confirm. The app builds and submits the transaction on the client's behalf. Partners integrating directly from their own infrastructure call the deployer themselves — see the [Integration Guide](/dedicated-client-vaults/integration-guide).
Either way, that one transaction:
* Clones a fresh vault contract for the caller
* Wires the caller as the owner with deposit and withdrawal rights
* Configures management and performance fees
* Pulls the initial deposit from the caller and mints shares in return
* Emits a `VaultDeployed` event with the new vault's address
After the transaction, the vault is fully independent — the deployer has no further control over it. The client lands on the new vault with shares already in their wallet; there is no separate "first deposit" step.
### 3. Selecting a strategy
Strategy selection is off-chain and costs no gas — the client signs an EIP‑712 typed-data message from their wallet, and once submitted Tesseract picks the vault up and begins managing it. The same mechanism is used to switch strategies later as risk preferences change.
* **Retail.** Pick a strategy from the list in [app.tesseract.fi](https://app.tesseract.fi) and sign the prompt that appears in the wallet — the app builds the message and submits the signature.
* **Integrators.** Build and sign the EIP‑712 message yourself, then `PUT /vaults/{vault}/strategy` on the Public API. See [Strategy Assignment](/dedicated-client-vaults/integration-guide/scenario-a/strategy-assignment) for the schema and a worked example.
### 4. Operating the vault
Once a strategy is assigned, Tesseract Investment Oy executes the discretionary portfolio management mandate at the vault level — allocating into yield sources, rebalancing, and handling risk management on the client's behalf. Assets never leave the individual vault contract to enter a shared pool.
Day-to-day vault operations have two paths. Retail clients use [app.tesseract.fi](https://app.tesseract.fi), which handles approvals, transaction construction, and fallback between instant and scheduled withdrawals automatically. Integrators call the vault and its `WithdrawManager` directly — see the [Integration Guide](/dedicated-client-vaults/integration-guide) for code-level walkthroughs.
**Top-up.** Add to an existing vault by depositing more of the underlying asset — shares are minted immediately, and Tesseract allocates the new capital on the next management cycle. Retail: use the "Deposit" action in the app. Integrators: approve the asset and call `deposit` on the vault — see [Deposits](/dedicated-client-vaults/integration-guide/scenario-a/deposits).
**Instant withdrawal.** For amounts that fit within the vault's liquid balance, withdrawals are a single transaction and funds arrive in the same block. Retail: use the "Withdraw" action in the app. Integrators: call `withdraw` or `redeem` on the vault; if the amount exceeds instant capacity the call reverts and you fall back to the scheduled flow — see [Instant Withdrawals](/dedicated-client-vaults/integration-guide/scenario-a/instant-withdrawals).
**Scheduled withdrawal.** For larger amounts, withdrawal is a three-step flow spread over up to \~24 hours: request → wait for Tesseract to release funds → claim within the withdrawal window. Retail: the app walks you through all three steps. Integrators: call `requestShares` on the vault's `WithdrawManager`, poll for release, then call `redeemFromRequest` on the vault — see [Scheduled Withdrawals](/dedicated-client-vaults/integration-guide/scenario-a/scheduled-withdrawals).
Yield accrues to each vault's positions and compounds automatically into the share price — no manual claim, no separate rewards token. See [Vault Shares](/dedicated-client-vaults/vault-shares) for how shares, share price, and auto-compounding work.
### 5. Reading vault state
Every vault has a public page in the Tesseract app — for example, [app.tesseract.fi/vault/0xe1c3a197…76a9](https://app.tesseract.fi/vault/0xe1c3a197d16ef96a7c8e7c5f6b83b5e032cd76a9) — showing balance, share price, performance, and transaction history. Clients use this as their primary dashboard.
Behind the same data, vault state is available two ways for integrators:
* **Directly on-chain.** Share price, balance, asset, total assets — the vault is a standard ERC‑4626 contract. Any ERC‑4626 tooling works.
* **Via the** [**Public API**](/dedicated-client-vaults/reference/public-api)**.** Vault discovery, decoded transaction history, and performance time-series (APY/APR, TVL, share price over time).
For a partner integrating into their own stack, the Public API is the single canonical entry point for reporting. No periodic reconciliation is required — share price and positions are always derivable from on-chain state.
### Components at a glance
| Component | Purpose | Public surface |
| ----------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `Whitelisting` | KYC-gated access control | `isWhitelisted`, `whitelistExpiration` |
| Vault Deployer (per asset) | Creates dedicated vaults | `deployVault`, `deployVaultWithPermit` |
| Vault (ERC‑4626) | Holds client assets, mints/burns shares | Standard ERC‑4626 (`deposit`, `redeem`, `withdraw`, `balanceOf`, `totalAssets`, …) |
| `WithdrawManager` (per vault) | Scheduled-withdrawal requests for amounts exceeding instant liquidity | `requestShares`, together with the vault's `redeemFromRequest` |
| Public API | Vault discovery, transactions, performance, strategy assignment | `api.vault.tesseract.fi` |
See [Contract Methods](/dedicated-client-vaults/reference/contract-methods) for full signatures.
# Vault Shares
Every dedicated vault issues its own share token on deployment. These shares represent the client's position in the vault — the accounting mechanism by which deposits, yield, and withdrawals are tracked on-chain.
### One token per vault
Each vault is a standalone ERC‑4626 contract and its own ERC‑20 share token. Share symbols follow the `te{Asset}` convention — `teUSDC`, `teWETH`, `teWBTC` — matching the vault's underlying asset.
When a client deposits, shares are minted to their wallet. When they withdraw, shares are burned proportionally to the amount withdrawn. The total supply of a given vault's shares always corresponds to 100% ownership of that vault — since there's one vault per client, the client holds the full supply.
### Share price and auto-compounding
A vault's share price is `totalAssets / totalSupply`. As yield accrues into the vault's positions, `totalAssets` grows; `totalSupply` stays constant (no new shares are issued for yield). The share price goes up, and each existing share becomes worth more of the underlying asset.
This is auto-compounding by construction — there is no separate rewards token, no claim step, and no re-staking. The yield is inside the vault from the moment it's earned, and it keeps earning.
Convert between shares and underlying assets using standard ERC‑4626 views:
```solidity
function convertToAssets(uint256 shares) external view returns (uint256);
function convertToShares(uint256 assets) external view returns (uint256);
function totalAssets() external view returns (uint256);
```
### Non-transferable
Vault shares are **non-transferable** outside of permitted operational flows (deposit, withdrawal, scheduled-withdrawal mechanics). `transfer` and `transferFrom` to arbitrary addresses will revert.
This is deliberate and structural:
* **Regulatory.** Shares are non-transferable by design, which is intended to keep the DCV outside securities and collective-investment-scheme characterisation. Tesseract's legal analysis supporting this design is available to institutional counterparties under NDA.
* **Ownership integrity.** The vault's owner on-chain is the wallet that deployed it. Non-transferability preserves that identity through the vault's entire lifetime.
* **Compliance.** Whitelist-based access means every address interacting with the vault is KYC'd — transferring shares to a non-whitelisted wallet would bypass this.
The practical consequence: shares are cryptographic proof of position, not a tradable instrument. They can be read, priced, and redeemed, but not sold on a secondary market.
### Reading client positions
For a simple "how much is this client's position worth":
```ts
const shares = await vault.balanceOf(owner)
const assets = await vault.convertToAssets(shares)
```
For decoded transaction history (deposits, withdrawals, share mints and burns) and performance time-series, use the [Public API](/dedicated-client-vaults/reference/public-api).
### On deployment
The deployer pulls the initial deposit from the caller and mints shares in the same transaction — see [Deploying a Vault](/dedicated-client-vaults/integration-guide/scenario-a/deploying-a-vault) for the exact mechanics. The first share price is close to 1:1 against the underlying and drifts upward as yield accrues.
# Roles & Access
Access to Dedicated Client Vaults is split into two layers: what your **team can do in the Tesseract dashboard**, and who can **move funds on-chain**. They are deliberately separate — no dashboard role can move funds.
### Dashboard roles
When your organisation is onboarded you can invite team members and assign each a role. Roles are ready-made permission sets (individual permissions can also be fine-tuned per user):
| Role | What it can do |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **Viewer** | Read-only across the dashboard — clients, KYC status, wallets, vaults and reports. |
| **Whitelisting Manager** | Everything a Viewer can, **plus verify and whitelist wallets** for on-chain access. |
| **Admin** | Full access, including managing team members (inviting, suspending, adjusting permissions). Provisioned at onboarding. |
### It all ends at wallet whitelisting
The most any dashboard role can do to affect on-chain activity is **whitelist a wallet** — the job of the Whitelisting Manager. Whitelisting only approves a wallet to interact with vaults; it moves no funds.
**Deposits and withdrawals are authorised solely by the whitelisted wallet itself** — no dashboard role, and no one else, can move funds on your behalf. Tesseract's discretionary management rebalances within your chosen strategy under separate, tightly scoped controls and can **never** withdraw to an external address; funds only ever move back to your own whitelisted wallet.
### Recommended: whitelist an MPC wallet or a multisig
Because on-chain control comes down to one wallet, the security of your vault funds is the security of the wallet you whitelist. We recommend whitelisting a wallet that already carries your organisation's custody and approval controls — an **MPC wallet** (e.g. Fireblocks) or an **on-chain multisig / smart account** (e.g. Safe) — so vault interaction reuses your existing security practices (multiple approvers, signing thresholds, transaction policies, audit trails) with no separate approval layer to maintain.
***
See also: [Prerequisites: KYC & Whitelisting](/dedicated-client-vaults/integration-guide/scenario-a/prerequisites) · [FAQ](/dedicated-client-vaults/faq).
# Fees & Commercial Model
### Fee Structure
| Fee | Amount |
| --------------- | -------------------- |
| Management fee | 0.25% on AUM |
| Performance fee | 30% on vault profits |
| Deposit fee | 0% |
| Withdrawal fee | 0% |
### Indicative Yields
| Asset | Gross Indicative Yield |
| ------------------ | ------------------------------------------ |
| Stablecoins (USDC) | \~5–6% (Conservative) / \~8–12% (Advanced) |
| Ethereum (ETH) | \~4–6% |
| Bitcoin (wBTC) | \~3–5% |
> ***Indicative yield footnote.** Indicative yields reflect gross annualised returns targeted for comparable DCV mandates over the twelve-month period ending 31 March 2026, before management and performance fees. Yields are variable, not a forecast and not a guarantee, and will differ between clients, strategies, and periods. Past performance is not indicative of future results.*
### Commercial Model
Distribution partners can integrate DCVs directly into their own product and offer Tesseract yield to their end clients. The integration path — what's required on your side, how users onboard, how vaults are operated, and how reporting flows back — is covered in the [Integration Guide](/dedicated-client-vaults/integration-guide) (Scenario B specifically).
Two commercial structures are available for distribution partners:
1. **Introducer / Distribution Agreement (preferred).** Partners earn a revenue share of the performance fee for clients they introduce. Early supporters receive higher revenue share percentages, which decline as more partners join the network.
2. **Technology Access Fee.** An alternative model based on AUM deployed, useful where revenue sharing faces regulatory constraints (e.g. for US-regulated entities).
The choice of model, exact revenue share, and any per-client terms are agreed contractually during partnership setup on a per-client basis — [get in touch](https://tesseract.fi/#contact-us).
***
> **Risks.** Discretionary portfolio management of crypto-assets involves significant risks, including smart contract risk, DeFi protocol risk, oracle risk, liquidity risk, market stress risk, counterparty risk, custody risk and regulatory change risk, and the risk of total loss of capital. Yields are indicative only, not guaranteed, and will vary.
# Compliance & Onboarding
> **Availability.** Tesseract Investment Oy does not provide services to persons in the United States, the United Kingdom, the United Arab Emirates, Japan, South Korea, Singapore or Australia. Service availability in other jurisdictions is subject to Tesseract's assessment of applicable regulatory and sanctions requirements.
### Overview
All clients onboarding to Tesseract Dedicated Client Vaults must complete Know Your Customer (KYC) or Know Your Business (KYB) verification before vault deployment. These are legal obligations under the EU Anti-Money Laundering Directives (AMLD), FATF Recommendations, and Finland's AML Act.
Tesseract uses **Sumsub** as its secure verification provider for both KYB and KYC flows.
### KYB Requirements (Corporate Clients)
The KYB flow has three parts: a company questionnaire, company documents, and identity checks for key individuals.
#### 1. Company Questionnaire
The questionnaire covers basic company and tax information:
* **Company details:** legal name, legal form, registration number, registration authority, tax residency, registered address, and contact details (email and phone)
* **Legal Entity Identifier (LEI):** required for all corporate clients
* **PEP declaration:** whether any beneficial owners or directors are politically exposed persons or closely related to them
* **Origin of assets:** main sources of the company's funds (e.g. operating income, dividends, loans, sale of property or company, investment income)
* **Business profile:** description of activities, main industries, key markets or countries of operation, and basic financial information such as turnover and balance sheet size
* **Expected activity:** approximate size and frequency of transactions and which services are intended to be used
#### 2. Company Documents
Clear electronic copies of core corporate documents are required:
* Certificate of incorporation or certificate of registration
* Memorandum and articles of association or equivalent governing documents
* Shareholder register showing current ownership
* Recent company registry extract from an official state or trade registry
* Proof of registered address (e.g. recent utility bill, bank statement, or official letter)
> **Freshness requirements:** Some documents must be recent (max 3 months old) and clearly dated and signed by the issuer or responsible party. These include: shareholder register, official registry extract, and any incorporation document provided as a registry extract.
#### 3. KYC Checks for Key Individuals
As part of KYB, the following individuals must be verified:
* **At least one legal representative** authorized to sign on behalf of the company (includes liveness check)
* **Ultimate Beneficial Owners (UBOs)** — individuals who directly or indirectly own or control more than 25% of shares/voting rights
* **Directors and senior management** where required by internal procedures
Each person completes an individual KYC flow: government-issued ID and a selfie/video liveness check (for representatives).
### KYC Requirements (Individual Clients)
For individual clients, the KYC process focuses on confirming identity, personal information, and AML-relevant background.
#### Information Required
* **Personal details:** full name, date of birth, nationality/nationalities, residential address, contact details, tax residency and TIN
* **PEP declaration:** whether you are a politically exposed person, family member, or close associate
* **Origin of assets:** source of funds (e.g. salary, savings, proceeds from sales, inheritance, investment gains including digital assets)
* **Employment and financial profile:** employment status, occupation, industry sector, income/wealth ranges
* **Intended use:** planned services, approximate transaction size and frequency
#### Documents Required
* Valid government-issued identity document (passport or national ID card)
* Selfie or live video for liveness and face match
* Proof of address — utility bill, bank statement, or official letter, max 3 months old
> In certain circumstances, additional source of funds and wealth documentation may be requested.
### Onboarding Process
The client journey is fully online and runs inside the Tesseract Compliance app at [compliance.tesseract.fi](https://compliance.tesseract.fi):
1. **Sign in** and pick KYC (individual) or KYB (company).
2. **Complete the Sumsub flow** — questionnaire, document uploads, and ID / liveness checks all happen inside the app. For KYB, key persons receive individual links for their own KYC steps.
3. **Suitability assessment.** Tesseract Investment Oy conducts a suitability assessment in accordance with MiCAR Article 81 and ESMA's 2025 Guidelines on suitability, before any vault is deployed.
4. **Automated checks** — Sumsub validates documents and screens against sanctions and PEP lists. Follow-up questions, if any, appear inline.
5. **Connect a wallet and sign the ownership challenge.** One or more wallets can be added; each is screened for AML risk.
6. **Whitelisting.** Once KYC/KYB, the suitability assessment and wallet screening pass, Tesseract writes each wallet to the on-chain `Whitelisting` contract with a KYC-expiration timestamp. The wallets can now deploy and operate vaults.
### Two onboarding paths
The flow above describes the standard **direct** path — the client completes KYC/KYB themselves via [compliance.tesseract.fi](https://compliance.tesseract.fi) and Sumsub. This covers both retail individuals and institutions onboarding as their own Tesseract client.
**Partner-led onboarding** (custodian model) is an alternative path for partners offering DCVs to their own end users. The partner and Tesseract agree on a compliance model up front — full KYC by Tesseract, reliance on the partner's existing KYC, or a hybrid — and the partner provisions users programmatically via Tesseract's Compliance API. See [Scenario B](/dedicated-client-vaults/integration-guide/scenario-b).
Both paths end the same way: the wallet is written to the on-chain `Whitelisting` contract with a KYC-expiration timestamp.
# Integration Guide
Step-by-step instructions for integrating Tesseract Dedicated Client Vaults into your own infrastructure.
Start with [**Choose Your Scenario**](/dedicated-client-vaults/integration-guide/choose-your-scenario) to pick the right path based on your business model. The rest of this guide is organized into two scenarios:
* [**Scenario A**](/dedicated-client-vaults/integration-guide/scenario-a) — you're managing vaults for yourself (treasury, own product). You onboard directly through Tesseract's compliance, your wallet gets whitelisted, and from there you deploy and operate vaults against the contracts directly.
* [**Scenario B**](/dedicated-client-vaults/integration-guide/scenario-b) — you're managing vaults on behalf of your own end users (custodian model). You become a Tesseract partner, align on a compliance model, onboard users through an M2M integration, and then run the same on-chain operations per-user.
Both scenarios converge on the same technical surface. Scenario B layers additional partnership and compliance steps on top of everything in Scenario A.
See also [**Indexing Vaults**](/dedicated-client-vaults/integration-guide/indexing-vaults) for data-consumer use cases — pulling vault lists for your own addresses via the Public API, or indexing every vault Tesseract creates on-chain.
For canonical addresses, method signatures, and API references used throughout this guide, see [Reference](/dedicated-client-vaults/reference).
# Choose Your Scenario
There are two fundamentally different integration shapes for DCVs. Pick the one that matches your business model — the on-chain technical work is the same, but the onboarding and compliance paths differ.
### Scenario A — You manage your own vaults
Pick this if:
* You're holding your own treasury in DCVs, or
* You're building a product where **your own business** is the client of Tesseract (not your end users), or
* You're an individual or a single institutional client deploying vaults for your own account, or
* You hold the relevant licenses on your side that allow you to operate a single vault with us and pool your own clients' assets inside it — [get in touch](https://tesseract.fi/#contact-us) and we'll be happy to discuss this path.
**What it looks like:**
1. You (or your company) complete KYC/KYB with Tesseract via [compliance.tesseract.fi](https://compliance.tesseract.fi).
2. Your wallet gets whitelisted on-chain. From that point on, it can deploy and operate vaults directly against the contracts.
3. You deploy vaults, deposit, withdraw, select strategies, and read state — using the smart contracts and the Public API directly from your own infrastructure.
There's no separate partnership required — Tesseract treats this as a direct client relationship. The only real difference from using the Tesseract app is that you drive everything from your own backend or custodial signer instead of the web UI.
**Go to →** [Scenario A: Manage Your Own Vaults](/dedicated-client-vaults/integration-guide/scenario-a)
### Scenario B — You manage vaults for your end users
Pick this if:
* You're a custodian, exchange, fintech, or wallet provider offering Tesseract DCVs to **your own customer base**, and
* Each of your end users will become a Tesseract client in their own right (either under their own KYC or under a reliance arrangement with Tesseract).
**What it looks like:**
1. You and Tesseract sign a partnership agreement and agree on the compliance split (reliance on your KYC, your users go through Tesseract's KYC, or a mix).
2. You're provisioned for Auth0 M2M access so you can onboard users into Tesseract's compliance system programmatically.
3. Optionally, you embed Tesseract's compliance app into your own product so users stay within your UI during KYC. *(This integration is currently available on request — contact us for the detailed spec.)*
4. For each cleared end user, the on-chain flow is the same as Scenario A — how you wire it up is flexible: each end user's wallet can be whitelisted individually, or you can operate vaults on their behalf from one or a group of partner-controlled wallets under a single account. Deposits / withdrawals / strategy assignments all happen against the same contracts.
Scenario B is a proper partnership and requires a commercial conversation before you can start technical integration. Once set up, the per-user on-chain steps link straight into the Scenario A material.
**Go to →** [Scenario B: Manage Vaults for End Users](/dedicated-client-vaults/integration-guide/scenario-b)
### Not sure?
If you're unsure which scenario fits, start with Scenario A — it's what most partners begin with for internal testing, and it's always a prerequisite for understanding what Scenario B delegates to you vs. to your users.
If you need Scenario B but aren't yet in conversation with us, [get in touch](https://tesseract.fi/#contact-us) before going further.
# Scenario A: Manage Your Own Vaults
You're managing DCVs for yourself — treasury, own product, or direct client use. The technical surface is small: one off-chain prerequisite (KYC + whitelisting), a handful of on-chain calls, and the Public API for reporting.
This scenario is organized in the order you'll actually do things:
1. [**Prerequisites: KYC & Whitelisting**](/dedicated-client-vaults/integration-guide/scenario-a/prerequisites) — how your wallet gets on the on-chain whitelist.
2. [**Deploying a Vault**](/dedicated-client-vaults/integration-guide/scenario-a/deploying-a-vault) — a single transaction against a Vault Deployer.
3. [**Deposits**](/dedicated-client-vaults/integration-guide/scenario-a/deposits) — adding capital to an existing vault.
4. [**Instant Withdrawals**](/dedicated-client-vaults/integration-guide/scenario-a/instant-withdrawals) — single-transaction withdrawals covered by liquid balance.
5. [**Scheduled Withdrawals**](/dedicated-client-vaults/integration-guide/scenario-a/scheduled-withdrawals) — the three-step flow for larger amounts.
6. [**Strategy Assignment**](/dedicated-client-vaults/integration-guide/scenario-a/strategy-assignment) — signing an EIP‑712 message to assign a strategy to a fresh vault.
7. [**Reading Vault Data**](/dedicated-client-vaults/integration-guide/scenario-a/reading-vault-data) — using the Public API (and the on-chain ERC‑4626 interface) for reporting.
Throughout, code examples are in TypeScript with [viem](https://viem.sh). The same operations work equally well from ethers.js, foundry-cast, Python web3, or any Ethereum tooling — the contracts are standard.
Canonical addresses and method signatures are in [Reference](/dedicated-client-vaults/reference).
# Prerequisites: KYC & Whitelisting
Before any wallet can deploy or operate a vault, it must be on Tesseract's on-chain `Whitelisting` contract with a non-expired entry. The steps are fixed:
### 1. Complete KYC / KYB
Go to [compliance.tesseract.fi](https://compliance.tesseract.fi) and complete the onboarding flow. For a company, this is a KYB (verification of the legal entity, beneficial owners, and directors); for an individual, it's a standard KYC. Full details of what's required are in [Compliance & Onboarding](/dedicated-client-vaults/compliance-and-onboarding).
### 2. Register the wallet you'll use
During onboarding you're asked to provide the wallet address(es) you'll use for vault operations and to sign a wallet-ownership message from each. Tesseract runs an AML screen on each wallet.
### 3. Wallet gets whitelisted on-chain
Once KYC/KYB clears and the wallet passes AML screening, Tesseract writes the wallet to the `Whitelisting` contract with a KYC-expiration timestamp. From that moment the wallet can deploy and operate vaults.
You can check the whitelist state on-chain at any time:
```ts
import {createPublicClient, http} from 'viem'
import {mainnet} from 'viem/chains'
const client = createPublicClient({chain: mainnet, transport: http()})
const whitelistingAddress = '0x25f1a2Ce5b681592E4196616f72aa27593EB5df8'
const whitelistingAbi = [
{
type: 'function', stateMutability: 'view',
name: 'isWhitelisted',
inputs: [{name: 'account', type: 'address'}],
outputs: [{type: 'bool'}],
},
{
type: 'function', stateMutability: 'view',
name: 'whitelistExpiration',
inputs: [{name: 'account', type: 'address'}],
outputs: [{type: 'uint256'}],
},
] as const
const isWhitelisted = await client.readContract({
address: whitelistingAddress,
abi: whitelistingAbi,
functionName: 'isWhitelisted',
args: [myWallet],
})
```
### 4. KYC renewal
Whitelist entries expire. Renewal typically requires going through the KYC flow again — Tesseract will email you shortly before your expiration date with instructions for what's needed. Once the renewal is cleared, the new expiration is written back to the on-chain whitelist. Until the wallet is re-whitelisted after expiry, new on-chain operations (deploy, deposit, withdraw, strategy change) revert for that wallet. Read `whitelistExpiration` directly from the `Whitelisting` contract if you want an independent view of remaining validity.
### The wallet is your access credential
Only the whitelisted wallet can move funds in a vault — deposits and withdrawals are authorised by that wallet, and no one can move funds on your behalf. Because on-chain control comes down to this one wallet, **the security of your vault funds is the security of the wallet you whitelist** — so consider whitelisting an MPC wallet or multisig that already carries your custody and approval controls. See [Roles & Access](/dedicated-client-vaults/roles-and-access) for the dashboard roles and the recommended setup.
### Using multiple wallets
A single client may have several whitelisted wallets (hot, cold, multisig, custodial). Each must be registered and whitelisted individually. Note that a vault is tied to the wallet that created it — operational rights on a given vault stay with that wallet.
***
Once your wallet is whitelisted, continue to [**Deploying a Vault**](/dedicated-client-vaults/integration-guide/scenario-a/deploying-a-vault).
# Deploying a Vault
A vault is created in a single transaction against the Vault Deployer for the asset you want to hold. The deployer pulls your initial deposit and mints shares to your wallet in the same call.
### Pick the right deployer
One deployer per asset:
| Asset | Deployer |
| ----- | ---------------------------------------------------------------------------------------------------------------------------- |
| USDC | [`0xe4D85722dB649d3890f9DBA4510F1A16AD942FD9`](https://etherscan.io/address/0xe4D85722dB649d3890f9DBA4510F1A16AD942FD9#code) |
| WBTC | [`0x55073cdF0b0E42C8B807A265EADff69973274a8d`](https://etherscan.io/address/0x55073cdF0b0E42C8B807A265EADff69973274a8d#code) |
| WETH | [`0x6701241e65d4baFC399Ca4358E95960aF3C041C4`](https://etherscan.io/address/0x6701241e65d4baFC399Ca4358E95960aF3C041C4#code) |
### Read the current minimum initial deposit
Before deploying, read the minimum initial deposit from the deployer — it's configured per asset and can change, so read it on-chain rather than hard-coding.
```ts
const deployerAbi = [
{type: 'function', stateMutability: 'view', name: 'minInitialDeposit',
inputs: [], outputs: [{type: 'uint256'}]},
] as const
const minDeposit = await client.readContract({
address: deployer, abi: deployerAbi, functionName: 'minInitialDeposit',
})
```
### Approve the initial deposit
The deployer needs to be able to pull `initialDeposit` of the underlying asset from your wallet:
```ts
const assetAbi = [{
type: 'function', stateMutability: 'nonpayable', name: 'approve',
inputs: [{type: 'address'}, {type: 'uint256'}],
outputs: [{type: 'bool'}],
}] as const
await walletClient.writeContract({
address: underlyingToken,
abi: assetAbi, functionName: 'approve',
args: [deployer, initialDeposit],
})
```
If the underlying token supports [EIP‑2612 permit](https://eips.ethereum.org/EIPS/eip-2612) (USDC does), you can skip the separate approval transaction by using `deployVaultWithPermit` instead — see below.
### Call `deployVault`
```ts
const deployAbi = [{
type: 'function', stateMutability: 'nonpayable', name: 'deployVault',
inputs: [
{name: 'initialDeposit', type: 'uint256'},
{name: 'maxManagementFee', type: 'uint256'},
{name: 'maxPerformanceFee', type: 'uint256'},
],
outputs: [/* FusionInstance struct — read from the event instead */],
}] as const
// Fees are in basis points (100 bps = 1%). Default DCV terms are
// 0.25% management (25 bps) and 30% performance (3000 bps) — pass those
// as the slippage caps, unless you've agreed different terms with Tesseract.
const MAX_MGMT_FEE = 25n // 0.25%
const MAX_PERF_FEE = 3000n // 30%
const hash = await walletClient.writeContract({
address: deployer,
abi: deployAbi,
functionName: 'deployVault',
args: [initialDeposit, MAX_MGMT_FEE, MAX_PERF_FEE],
})
const receipt = await client.waitForTransactionReceipt({hash})
```
`maxManagementFee` and `maxPerformanceFee` are slippage guards — the transaction reverts if the deployer's currently configured fees exceed them. Use the agreed contractual values so an accidental on-chain fee bump can't deploy a vault with fees higher than what you signed up for.
### Extract the vault address
The deployer emits a `VaultDeployed` event. Parse it from the receipt:
```ts
import {parseAbiItem, decodeEventLog} from 'viem'
const vaultDeployedEvent = parseAbiItem(
'event VaultDeployed(address indexed plasmaVault, address indexed owner, address accessManager, address feeManager, address rewardsManager, address withdrawManager, address contextManager, address priceManager)'
)
const log = receipt.logs.find(l => l.address.toLowerCase() === deployer.toLowerCase())
const decoded = decodeEventLog({abi: [vaultDeployedEvent], data: log.data, topics: log.topics})
const vault = decoded.args.plasmaVault
const withdrawManager = decoded.args.withdrawManager
```
Save `plasmaVault` (the vault address you'll interact with for deposits / withdrawals) and `withdrawManager` (per-vault manager for scheduled withdrawals). Both are also discoverable later via the [Public API](/dedicated-client-vaults/reference/public-api).
### Using permit (one transaction)
For underlying tokens that support EIP‑2612, you can skip the separate approval and deploy in a single transaction:
```ts
// 1. Generate a permit signature for `initialDeposit` to `deployer`
const {v, r, s, deadline} = await signPermit({...})
// 2. Call the permit variant
await walletClient.writeContract({
address: deployer,
abi: /* deployVaultWithPermit ABI */,
functionName: 'deployVaultWithPermit',
args: [initialDeposit, mgmtFee, perfFee, deadline, v, r, s],
})
```
***
Once your vault exists, continue to [**Strategy Assignment**](/dedicated-client-vaults/integration-guide/scenario-a/strategy-assignment) to start managing it, or [**Deposits**](/dedicated-client-vaults/integration-guide/scenario-a/deposits) if you want to add more capital first.
# Deposits
Topping up an existing vault is a standard ERC‑4626 `deposit` call. No additional authorization or signatures are required — the wallet that created the vault (or any wallet explicitly granted deposit rights) can deposit at any time.
### Approve the vault
```ts
await walletClient.writeContract({
address: underlyingToken,
abi: erc20Abi,
functionName: 'approve',
args: [vault, amount],
})
```
### Deposit
```ts
const vaultAbi = [{
type: 'function', stateMutability: 'nonpayable', name: 'deposit',
inputs: [
{name: 'assets', type: 'uint256'},
{name: 'receiver', type: 'address'},
],
outputs: [{name: 'shares', type: 'uint256'}],
}] as const
const hash = await walletClient.writeContract({
address: vault,
abi: vaultAbi,
functionName: 'deposit',
args: [amount, receiver], // receiver is usually the same wallet
})
```
Shares are minted to `receiver` immediately. The share price reflects the accumulated yield at the time of the transaction.
### Using `mint` instead of `deposit`
Standard ERC‑4626 semantics apply:
* `deposit(assets, receiver)` — you specify the asset amount, the vault calculates and mints shares.
* `mint(shares, receiver)` — you specify the share amount, the vault calculates and pulls assets.
Use `deposit` when you know the asset amount (most common). Use `mint` when you want a precise share count (rare).
### Using permit (one transaction)
For underlying tokens that support EIP‑2612 (e.g. USDC), you can skip the separate approval and deposit in a single transaction:
```ts
// 1. Generate a permit signature authorizing the vault to pull `amount` from the wallet
const {v, r, s, deadline} = await signPermit({...})
// 2. Call the permit variant directly on the vault
await walletClient.writeContract({
address: vault,
abi: /* depositWithPermit ABI */,
functionName: 'depositWithPermit',
args: [amount, receiver, deadline, v, r, s],
})
```
`depositWithPermit` runs the permit and the deposit atomically — if the permit signature is invalid or expired but the wallet already has sufficient allowance, the deposit still succeeds; otherwise the transaction reverts.
### New shares start earning immediately
Deposited assets sit in the vault until Tesseract's next management cycle picks them up and allocates them into positions. From your perspective, share price continues to accrue as before — you don't need to wait for allocation before shares start representing a yield-bearing position.
***
Continue to [**Instant Withdrawals**](/dedicated-client-vaults/integration-guide/scenario-a/instant-withdrawals) for the withdrawal flow.
# Instant Withdrawals
For amounts that fit within the vault's available liquidity, withdrawal is a single transaction. Call `withdraw` (specifying an asset amount) or `redeem` (specifying a share amount) and receive the underlying asset in the same block.
There is no reliable on-chain view for "how much can clear instantly right now" — the vault's standard ERC‑4626 `maxWithdraw` / `maxRedeem` don't reflect the real instant-withdrawal capacity. The correct pattern is to **try the instant call (or simulate it first) and fall back to the scheduled flow if it reverts.**
### Withdraw
```ts
const vaultAbi = [{
type: 'function', stateMutability: 'nonpayable', name: 'withdraw',
inputs: [
{name: 'assets', type: 'uint256'},
{name: 'receiver', type: 'address'},
{name: 'owner', type: 'address'},
],
outputs: [{name: 'shares', type: 'uint256'}],
}] as const
await walletClient.writeContract({
address: vault,
abi: vaultAbi,
functionName: 'withdraw',
args: [assets, receiver, owner],
})
```
`receiver` gets the asset; `owner` is the wallet whose shares are burned. For a straightforward own-withdrawal, `receiver === owner === msg.sender`.
### Redeem (by share count)
```ts
await walletClient.writeContract({
address: vault, abi: vaultAbi, functionName: 'redeem',
args: [shares, receiver, owner],
})
```
Use `redeem` when you want to burn a specific share count (e.g. "withdraw half of my position"). Use `withdraw` when you want a precise asset amount out.
### Falling back to scheduled
If the requested amount exceeds what the vault can free instantly, the call reverts. Detect this and fall back. Two patterns:
**Simulate first, then send.** Cleaner for production — you learn whether the call will succeed before asking the user to sign:
```ts
try {
await client.simulateContract({
address: vault, abi: vaultAbi, functionName: 'withdraw',
args: [assets, receiver, owner],
account: owner,
})
// Simulation succeeded — send the real transaction
await walletClient.writeContract({
address: vault, abi: vaultAbi, functionName: 'withdraw',
args: [assets, receiver, owner],
})
} catch (err) {
// Instant path can't satisfy — request a scheduled withdrawal
await requestScheduledWithdrawal(shares)
}
```
**Try directly, catch on revert.** Simpler, but costs the user a rejected signature / failed tx:
```ts
try {
await walletClient.writeContract({
address: vault, abi: vaultAbi, functionName: 'withdraw',
args: [assets, receiver, owner],
})
} catch (err) {
await requestScheduledWithdrawal(shares)
}
```
***
Continue to [**Scheduled Withdrawals**](/dedicated-client-vaults/integration-guide/scenario-a/scheduled-withdrawals) for the larger-amount flow.
# Scheduled Withdrawals
For amounts that don't clear instantly, use the three-step scheduled flow. It spans up to \~24 hours end-to-end.
### Who does what
| Step | Actor | Action |
| ---------- | ----------- | ------------------------------------------------------------------ |
| 1. Request | Vault owner | Call `requestShares` on the vault's `WithdrawManager` |
| 2. Release | Tesseract | Prepare liquidity in the background and release funds |
| 3. Claim | Vault owner | Call `redeemFromRequest` on the vault within the withdrawal window |
Each vault has its own `WithdrawManager` — its address is in the `VaultDeployed` event from when the vault was deployed, and discoverable via the [Public API](/dedicated-client-vaults/reference/public-api).
### Step 1 — Request shares
Approve your shares to be spent by the vault, then call `requestShares`:
```ts
const vaultErc20Abi = [{
type: 'function', stateMutability: 'nonpayable', name: 'approve',
inputs: [{type: 'address'}, {type: 'uint256'}],
outputs: [{type: 'bool'}],
}] as const
// Shares are ERC-20 on the vault itself — approve the vault
await walletClient.writeContract({
address: vault, abi: vaultErc20Abi, functionName: 'approve',
args: [vault, shares],
})
const withdrawManagerAbi = [{
type: 'function', stateMutability: 'nonpayable', name: 'requestShares',
inputs: [{name: 'shares', type: 'uint256'}], outputs: [],
}] as const
await walletClient.writeContract({
address: withdrawManager,
abi: withdrawManagerAbi,
functionName: 'requestShares',
args: [shares],
})
```
Your shares are now locked and a withdrawal window is opened on the `WithdrawManager`.
### Step 2 — Wait for release
Tesseract's operations prepare liquidity by exiting positions as needed and call `releaseFunds` on the `WithdrawManager` when ready. This typically takes minutes to hours and is capped by the release SLA.
Tesseract sends the client an email notification as soon as the funds are released and the claim window opens — for retail users, this is usually enough. Integrators that can't rely on email (custodial, headless, automated flows) should poll release status on-chain:
```ts
const wmViewAbi = [
{type: 'function', stateMutability: 'view', name: 'getLastReleaseFundsTimestamp',
inputs: [], outputs: [{type: 'uint256'}]},
{type: 'function', stateMutability: 'view', name: 'getWithdrawWindow',
inputs: [], outputs: [{type: 'uint256'}]},
{type: 'function', stateMutability: 'view', name: 'requestInfo',
inputs: [{name: 'account', type: 'address'}],
outputs: [/* WithdrawRequestInfo struct */]},
] as const
const releaseTs = await client.readContract({
address: withdrawManager, abi: wmViewAbi, functionName: 'getLastReleaseFundsTimestamp',
})
```
Once `releaseTs` advances past your request timestamp, your request is ready to claim.
### Step 3 — Redeem from request
While the window is still open, call `redeemFromRequest` on the **vault** (not the `WithdrawManager`):
```ts
const vaultClaimAbi = [{
type: 'function', stateMutability: 'nonpayable', name: 'redeemFromRequest',
inputs: [
{name: 'shares', type: 'uint256'},
{name: 'receiver', type: 'address'},
{name: 'owner', type: 'address'},
],
outputs: [{name: 'assets', type: 'uint256'}],
}] as const
await walletClient.writeContract({
address: vault,
abi: vaultClaimAbi,
functionName: 'redeemFromRequest',
args: [shares, receiver, owner],
})
```
The underlying asset is transferred to `receiver` and the shares are burned.
### If the window expires
If you don't claim before the window closes, the request is effectively cancelled and you need to start over from Step 1. Poll the release timestamp and submit the claim as soon as funds are available to avoid this.
### Partial claims
You can request a single large amount and claim it in multiple smaller calls to `redeemFromRequest`, as long as each claim stays within the window. The `WithdrawManager` tracks the remaining unclaimed shares of your request.
***
Continue to [**Strategy Assignment**](/dedicated-client-vaults/integration-guide/scenario-a/strategy-assignment) if you haven't assigned a strategy yet, or [**Reading Vault Data**](/dedicated-client-vaults/integration-guide/scenario-a/reading-vault-data) for reporting.
# Strategy Assignment
Strategy selection is off-chain metadata signed by the vault owner. There's no on-chain transaction and no gas cost — you sign an EIP‑712 typed-data message with the owner wallet and POST it to the Public API. Tesseract picks the vault up and starts managing it.
Strategy can be set and changed freely before the vault starts being actively managed. Once a vault is actively managed, changes may be restricted — if your change isn't accepted, contact Tesseract to arrange a managed transition.
### Discover available strategies
The set of strategies and their IDs is in the [Tesseract app](https://app.tesseract.fi) and exposed via the Public API. Each strategy has a UUID and is tied to a specific underlying asset (a USDC strategy can only be assigned to a USDC vault).
### Sign the message
The EIP‑712 schema is defined in the [Reference → Public API](/dedicated-client-vaults/reference/public-api#strategy-assignment-eip-712) page. Using viem:
```ts
import {createWalletClient, http} from 'viem'
import {mainnet} from 'viem/chains'
const walletClient = createWalletClient({
chain: mainnet,
account: /* your signer */,
transport: http(),
})
const timestamp = Math.floor(Date.now() / 1000)
const signature = await walletClient.signTypedData({
domain: {
name: 'Tesseract Public API',
version: '1',
chainId: 1,
},
types: {
SetStrategy: [
{name: 'vaultAddress', type: 'address'},
{name: 'strategyId', type: 'string'},
{name: 'timestamp', type: 'uint256'},
],
},
primaryType: 'SetStrategy',
message: {
vaultAddress: vault,
strategyId: selectedStrategyId,
timestamp: BigInt(timestamp),
},
})
```
### Submit to the Public API
```ts
const response = await fetch(
`https://api.vault.tesseract.fi/public/vaults/${vault}/strategy`,
{
method: 'PUT',
headers: {'content-type': 'application/json'},
body: JSON.stringify({
clientAddress: owner,
strategyId: selectedStrategyId,
signature,
timestamp,
}),
},
)
if (!response.ok) {
throw new Error(`Failed to assign strategy: ${response.status}`)
}
```
The API verifies:
* The signature recovers to `clientAddress`.
* `clientAddress` is the owner of the vault.
* `timestamp` is recent (a few minutes — sign and submit in the same flow).
* The vault is eligible for strategy change (see note above about actively-managed vaults).
### After assignment
Once the signature is accepted, Tesseract's management process picks up the vault on its next cycle and begins allocating positions according to the selected strategy. You can see the assignment reflected in the vault's detail via `GET /vaults/{vault}` — see [Reading Vault Data](/dedicated-client-vaults/integration-guide/scenario-a/reading-vault-data).
### Changing strategy later
Re-sign and re-submit with a different `strategyId` — each submission replaces the previous assignment. Strategy changes may be restricted once the vault is actively managed; if your submission is rejected, contact Tesseract to arrange a managed transition.
***
Continue to [**Reading Vault Data**](/dedicated-client-vaults/integration-guide/scenario-a/reading-vault-data).
# Reading Vault Data
Vault state is readable two ways: directly on-chain (standard ERC‑4626) and via the [Public API](/dedicated-client-vaults/reference/public-api) (vault discovery, decoded transactions, performance with live share-price snapshots). Use on-chain reads for per-transaction accounting; prefer the Public API for anything performance- or time-series-related.
### On-chain — ERC‑4626
Everything you need for basic accounting is already on the vault:
```ts
const vaultViewAbi = [
{type: 'function', stateMutability: 'view', name: 'asset',
inputs: [], outputs: [{type: 'address'}]},
{type: 'function', stateMutability: 'view', name: 'totalAssets',
inputs: [], outputs: [{type: 'uint256'}]},
{type: 'function', stateMutability: 'view', name: 'balanceOf',
inputs: [{type: 'address'}], outputs: [{type: 'uint256'}]},
{type: 'function', stateMutability: 'view', name: 'convertToAssets',
inputs: [{type: 'uint256'}], outputs: [{type: 'uint256'}]},
{type: 'function', stateMutability: 'view', name: 'convertToShares',
inputs: [{type: 'uint256'}], outputs: [{type: 'uint256'}]},
] as const
const [underlying, totalAssets, myShares] = await Promise.all([
client.readContract({address: vault, abi: vaultViewAbi, functionName: 'asset'}),
client.readContract({address: vault, abi: vaultViewAbi, functionName: 'totalAssets'}),
client.readContract({address: vault, abi: vaultViewAbi, functionName: 'balanceOf', args: [owner]}),
])
const myAssets = await client.readContract({
address: vault, abi: vaultViewAbi, functionName: 'convertToAssets',
args: [myShares],
})
```
Share price is `totalAssets / totalSupply`. The vault's value per share increases over time as yield compounds.
> ⚠️ **`totalAssets` and anything derived from it (share price, `convertToAssets`, `convertToShares`) only update when there's a transaction that touches the vault** — deposit, withdrawal, rebalance, fee accrual. Between transactions, the on-chain numbers are stale against the underlying positions' live value. If you read the vault at a quiet period, you won't see yield that has accrued in the underlying positions since the last touch.
>
> For live, continuously-refreshed share price and performance, use the [**Public API**](/dedicated-client-vaults/reference/public-api) — it publishes hourly snapshots with values simulated against current on-chain state, so they reflect yield accrued between vault transactions.
### Public API — discovery, transactions, performance
For anything beyond bare ERC‑4626 state, use the Public API. It lets you:
* Look up vaults for a single client address or a batch of addresses.
* Fetch per-vault detail (asset, status, shares, fees, assigned strategy).
* Read decoded transaction history (deposits, withdrawals, rebalances).
* Pull performance time-series (APY/APR, TVL, hourly share-price snapshots).
For the full list of endpoints, request / response schemas, and a live "try it" UI, see [**Reference → Public API**](/dedicated-client-vaults/reference/public-api) — it points to the published Swagger, which is the source of truth and stays in sync with the live service.
# Scenario B: Manage Vaults for End Users
You're offering Tesseract DCVs to your own customer base — custodian, exchange, fintech, or wallet provider. Each of your end users becomes a Tesseract client in their own right, and you orchestrate onboarding and day-to-day vault operations on their behalf.
Scenario B is a proper partnership, not a plug-and-play API. The on-chain surface is the same as [Scenario A](/dedicated-client-vaults/integration-guide/scenario-a) — the difference is everything that sits in front of it.
### What's involved
**Partnership and legal.** You and Tesseract agree on the commercial model ([Introducer / Distribution Agreement](/dedicated-client-vaults/fees-and-commercial-model) or Technology Access Fee), complete DDQ, and sign the partnership agreement. Your organization completes a KYB as the partnering entity.
**Compliance alignment.** We decide up front who runs KYC for your users — Tesseract Investment Oy (full KYC under our MiCA CASP authorisation), you (reliance on your existing AML program), or a hybrid. The choice depends on your regulatory status, jurisdiction, and user base. Tesseract runs ongoing AML screening on any wallet it whitelists regardless of the model chosen.
**Programmatic user onboarding (M2M).** You're provisioned with credentials for Tesseract's Compliance API and onboard each of your users into our compliance system via REST. Once a user is cleared, Tesseract writes their wallet to the on-chain `Whitelisting` contract with a KYC-expiration timestamp.
**Custody flexibility.** On-chain operations don't care who signs — what matters is that the signing wallet is whitelisted and owns the vault. You can have each end user sign from their own wallet, operate vaults from your custodial wallets per user, or (with the relevant licenses) pool users under a smaller set of partner-controlled wallets. The right shape is agreed during compliance setup.
**Optional compliance app embedding.** If you want users to complete KYC without leaving your product, Tesseract can provide an embeddable version of the Compliance app. This is available on request — we share the integration spec after partnership setup.
**Vault operations per user.** Once wallets are whitelisted, per-user vault deployment, deposits, withdrawals, strategy assignment, and reporting follow the same on-chain flow as Scenario A — see the [Scenario A material](/dedicated-client-vaults/integration-guide/scenario-a) for code-level walkthroughs that carry over one-to-one.
### What you get after partnership setup
* M2M credentials for the Compliance API, scoped to your partner account.
* Full request / response documentation for the Compliance API.
* The Compliance app embedding spec (if applicable).
* A named commercial and technical contact at Tesseract.
* Access to the reporting surface for all vaults under your partnership.
### How to start
Scenario B always starts with a commercial conversation. The technical documentation above is intentionally a summary — detailed specs and credentials are shared directly with partners after the initial discussion.
[**Get in touch**](https://tesseract.fi/#contact-us) to open the conversation.
# Indexing Vaults
Two different needs, two different answers.
### You just need your own vaults (or your users' vaults)
If all you care about is "give me the vaults for this wallet address, or for this list of wallet addresses" — use the Public API. No indexing, no event processing, no node operations required.
* `POST /vaults/query/by-client-addresses` takes a list of wallet addresses and returns the vaults owned by each.
* `GET /vaults/{vault}` returns full detail for a single vault.
See [Reading Vault Data](/dedicated-client-vaults/integration-guide/scenario-a/reading-vault-data) for a walkthrough and [Reference → Public API](/dedicated-client-vaults/reference/public-api) for the full endpoint list.
### You want to index every vault ever created
If you need a local view of all vaults created by Tesseract — for partner-wide dashboards, analytics, third-party data services, or anything you don't want routed through our API — index the on-chain `VaultDeployed` event.
* One event per vault, emitted by the [Vault Deployer](/dedicated-client-vaults/reference/contract-addresses#vault-deployers-one-per-supported-asset) for each asset.
* The event exposes the new vault's address and its associated manager contracts (access manager, fee manager, withdraw manager, etc.).
* Event schema: [Reference → Contract Methods → Vault Deployer](/dedicated-client-vaults/reference/contract-methods#vault-deployer-per-asset).
There is one deployer per supported asset (USDC / WETH / WBTC), so the indexer needs to watch all three contract addresses.
Once you have the vault address, everything else is standard — ERC‑4626 views on the vault, the vault's `WithdrawManager` for scheduled withdrawals, and the Public API for performance / decoded history.
# Reference
Canonical technical reference for Tesseract Dedicated Client Vaults.
* [Contract Addresses](/dedicated-client-vaults/reference/contract-addresses) — deployed addresses on Ethereum mainnet
* [Contract Methods](/dedicated-client-vaults/reference/contract-methods) — functions and events you interact with
* [Public API](/dedicated-client-vaults/reference/public-api) — reporting and vault-state API
* [Audit Reports](/dedicated-client-vaults/reference/audit-reports) — independent security audits
For step-by-step integration instructions, see the [Integration Guide](/dedicated-client-vaults/integration-guide).
# Contract Addresses
All Tesseract DCV contracts are deployed on **Ethereum mainnet**. Each contract is verified on Etherscan — follow the links for source code and ABI downloads.
### Compliance contracts
| Contract | Address | Purpose |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Whitelisting | [`0x25f1a2Ce5b681592E4196616f72aa27593EB5df8`](https://etherscan.io/address/0x25f1a2Ce5b681592E4196616f72aa27593EB5df8#code) | On-chain whitelist with per-address KYC expiration. A wallet must be whitelisted before it can deploy or operate a vault. |
### Vault deployers (one per supported asset)
Each deployer creates a new, dedicated vault configured for a specific underlying asset. Call `deployVault(...)` or `deployVaultWithPermit(...)` on the deployer for the asset you want to hold.
| Asset | Deployer Address | Share Symbol |
| ----- | ---------------------------------------------------------------------------------------------------------------------------- | ------------ |
| USDC | [`0xe4D85722dB649d3890f9DBA4510F1A16AD942FD9`](https://etherscan.io/address/0xe4D85722dB649d3890f9DBA4510F1A16AD942FD9#code) | teUSDC |
| WBTC | [`0x55073cdF0b0E42C8B807A265EADff69973274a8d`](https://etherscan.io/address/0x55073cdF0b0E42C8B807A265EADff69973274a8d#code) | teWBTC |
| WETH | [`0x6701241e65d4baFC399Ca4358E95960aF3C041C4`](https://etherscan.io/address/0x6701241e65d4baFC399Ca4358E95960aF3C041C4#code) | teWETH |
### Vault instances
Every client gets their own vault contract, created when they call a deployer. The address of the new vault is returned by `deployVault(...)` and emitted in the `VaultDeployed` event.
Each vault contract is a standard ERC‑4626 share vault — once you have the address, you can interact with it using any ERC‑4626 tooling or the [methods listed in the reference](/dedicated-client-vaults/reference/contract-methods).
**Reference deployed vault** (for ABI inspection and tooling setup):
[`0xe1c3a197d16eF96a7c8E7c5F6B83B5E032cD76a9`](https://etherscan.io/address/0xe1c3a197d16ef96a7c8e7c5f6b83b5e032cd76a9#code) — also viewable in the app at [app.tesseract.fi/vault/0xe1c3a197d16ef96a7c8e7c5f6b83b5e032cd76a9](https://app.tesseract.fi/vault/0xe1c3a197d16ef96a7c8e7c5f6b83b5e032cd76a9).
Use this as a template for wallet-connector configuration, wagmi/viem code generation, or ERC‑4626 interface probing. Functional behavior is identical across all deployed vaults.
### Supported assets
Underlying ERC‑20 tokens that Tesseract vaults wrap. Minimum deposits are configured per-deployer and may change — always read the current value from the deployer's `minInitialDeposit()` view before deploying.
| Asset | Token Address |
| ----- | --------------------------------------------------------------------------------------------------------------------- |
| USDC | [`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`](https://etherscan.io/token/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) |
| WBTC | [`0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599`](https://etherscan.io/token/0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599) |
| WETH | [`0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`](https://etherscan.io/token/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2) |
# Contract Methods
Public, read-accessible methods that integrators call directly on-chain. Full ABIs are available via Etherscan for each contract — see [Contract Addresses](/dedicated-client-vaults/reference/contract-addresses).
### Whitelisting
The access-control contract that gates all vault operations. A wallet must have a non-expired whitelist entry before it can deploy a vault or be the active signer on vault operations that require whitelisting.
```solidity
function isWhitelisted(address account) external view returns (bool);
function whitelistExpiration(address account) external view returns (uint256);
```
`isWhitelisted` returns `true` while the wallet's KYC is valid. `whitelistExpiration` returns the Unix timestamp of expiry (`0` means never whitelisted). Renewal typically requires the client to re-complete the KYC flow — Tesseract emails the client with instructions shortly before expiry, and the new expiration is written back on-chain once checks clear.
Write functions (`setWhitelist`, `setWhitelistBatch`) are restricted to the Tesseract operator role and are not part of the integration surface.
### Vault Deployer (per asset)
Call the deployer for the asset you want to hold. The deployer creates a fully configured dedicated vault in a single transaction and mints initial shares to the caller.
```solidity
function deployVault(
uint256 initialDeposit,
uint256 maxManagementFee,
uint256 maxPerformanceFee
) external returns (FusionInstance memory);
function deployVaultWithPermit(
uint256 initialDeposit,
uint256 maxManagementFee,
uint256 maxPerformanceFee,
uint256 deadline,
uint8 v,
bytes32 r,
bytes32 s
) external returns (FusionInstance memory);
```
Both functions revert with `NotWhitelisted` if the caller is not on the `Whitelisting` contract. `maxManagementFee` / `maxPerformanceFee` are slippage guards on current configured fees; pass generous upper bounds (or the exact current values) to avoid the transaction reverting on an in-flight fee update.
The address of the new vault is returned and emitted in `VaultDeployed`.
**View helpers** (read current configuration):
```solidity
function minInitialDeposit() external view returns (uint256);
function UNDERLYING_TOKEN() external view returns (address);
```
**Events:**
```solidity
event VaultDeployed(
address indexed plasmaVault,
address indexed owner,
address accessManager,
address feeManager,
address rewardsManager,
address withdrawManager,
address contextManager,
address priceManager
);
```
Index `VaultDeployed` to track new vaults as they're created. `plasmaVault` is the main vault address; `withdrawManager` is the per-vault manager used for scheduled withdrawals (see below).
### Vault (ERC‑4626)
Each vault is a standard ERC‑4626 share vault. Standard deposit / withdrawal / balance methods work as defined in [EIP‑4626](https://eips.ethereum.org/EIPS/eip-4626):
```solidity
function deposit(uint256 assets, address receiver) external returns (uint256 shares);
function mint(uint256 shares, address receiver) external returns (uint256 assets);
function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares);
function redeem(uint256 shares, address receiver, address owner) external returns (uint256 assets);
function totalAssets() external view returns (uint256);
function convertToShares(uint256 assets) external view returns (uint256);
function convertToAssets(uint256 shares) external view returns (uint256);
function balanceOf(address account) external view returns (uint256);
function asset() external view returns (address);
```
`withdraw` / `redeem` are **instant withdrawals** — they pull from idle cash and pre-authorized instant-withdrawal routes and execute in a single transaction. If the requested amount can't be satisfied instantly, the call reverts and you must fall back to the scheduled flow below.
In addition to the standard ERC‑4626 methods, the vault exposes an EIP‑2612 convenience entry point for deposits:
```solidity
function depositWithPermit(
uint256 assets,
address receiver,
uint256 deadline,
uint8 v,
bytes32 r,
bytes32 s
) external returns (uint256 shares);
```
`depositWithPermit` atomically consumes a permit signature on the underlying token and performs the deposit in a single transaction — no separate `approve` is needed. Only available for underlying tokens that implement EIP‑2612 (e.g. USDC). There are no permit variants for `mint`, `withdraw`, `redeem`, or `requestShares`.
Vault shares are **non-transferable** outside the permitted set — `transfer` / `transferFrom` are gated to operational flows.
For ABI inspection and tooling setup, use any deployed vault as a reference — e.g. [`0xe1c3a197d16eF96a7c8E7c5F6B83B5E032cD76a9`](https://etherscan.io/address/0xe1c3a197d16ef96a7c8e7c5f6b83b5e032cd76a9#code).
### Scheduled withdrawal (WithdrawManager + Vault)
For amounts that can't clear instantly, use the three-step scheduled flow. Each vault has its own `WithdrawManager` — its address is in the `VaultDeployed` event and also available from the vault via its access-manager setup.
```solidity
// On WithdrawManager — called by the vault owner
function requestShares(uint256 shares) external;
// On the vault — called by the vault owner once Tesseract releases funds
function redeemFromRequest(
uint256 shares,
address receiver,
address owner
) external returns (uint256 assets);
```
Flow:
1. **Approve** the vault to spend your shares (or use permit if supported).
2. Call `requestShares(shares)` on the vault's `WithdrawManager`. This opens a withdrawal window and locks the requested shares.
3. **Wait.** Tesseract prepares liquidity in the background (minutes to hours, capped at \~24h) and releases funds.
4. While the window is still open, call `redeemFromRequest(shares, receiver, owner)` on the vault to receive the underlying asset.
If the window expires before you claim, the request must be re-issued.
Read current state with:
```solidity
function requestInfo(address account) external view returns (WithdrawRequestInfo memory);
function getLastReleaseFundsTimestamp() external view returns (uint256);
function getWithdrawWindow() external view returns (uint256);
```
Strategy assignment is an off-chain flow (EIP‑712 signature submitted to the Public API) — see [Public API → Strategy assignment](/dedicated-client-vaults/reference/public-api#strategy-assignment-eip-712).
# Public API
The Tesseract Public API is the reporting and vault-state surface for integrators. It exposes vault discovery, transaction history, and performance data, and accepts the EIP‑712 signed request that assigns a strategy to a freshly deployed vault.
### Base URL
```
https://api.vault.tesseract.fi
```
### Interactive reference
Full request / response schemas, parameters, and live "try it" UI are published as Swagger:
🔗 [**https://api.vault.tesseract.fi/public/docs**](https://api.vault.tesseract.fi/public/docs)
Schemas are the source of truth — this page is a navigational summary, not a replacement.
### What you'll find there
| Purpose | Endpoint family |
| ----------------------------------------------------------------- | ---------------------------------------- |
| List vaults for one or more client wallet addresses | `POST /vaults/query/by-client-addresses` |
| Get a single vault's detail (asset, shares, fees, status) | `GET /vaults/{vault}` |
| List transactions for a vault (deposits, withdrawals, rebalances) | `GET /vaults/{vault}/transactions` |
| Assign a strategy to a deployed vault (EIP‑712 signed) | `PUT /vaults/{vault}/strategy` |
| Performance time-series (APY/APR, TVL, share price) | `GET /vaults/{vault}/performance` |
Authentication is not required for read endpoints — vault addresses themselves act as the key. The strategy-assignment endpoint validates an EIP‑712 signature against the vault's owner; see below for the schema.
**Performance snapshots.** The `performance` endpoint exposes hourly snapshots — share price and TVL are simulated against current on-chain state and refreshed each hour, so they reflect yield accrued between vault transactions (unlike a bare on-chain read, which only updates when the vault is touched).
### Strategy assignment (EIP‑712)
Strategy selection is off-chain metadata signed by the vault owner and submitted to `PUT /vaults/{vault}/strategy`. There is no on-chain transaction and no gas cost for the signer.
**Domain:**
```json
{
"name": "Tesseract Public API",
"version": "1",
"chainId": 1
}
```
**Types:**
```json
{
"SetStrategy": [
{ "name": "vaultAddress", "type": "address" },
{ "name": "strategyId", "type": "string" },
{ "name": "timestamp", "type": "uint256" }
]
}
```
**Message:**
```json
{
"vaultAddress": "0x...",
"strategyId": "",
"timestamp": 1716000000
}
```
`timestamp` is Unix seconds and must be recent (signatures expire after a short window — send within a few minutes of signing). Strategy changes may be restricted once a vault is actively managed; if your submission is rejected, contact Tesseract to arrange a managed transition.
A viem example — and the full REST call — is shown in the [Integration Guide](/dedicated-client-vaults/integration-guide/scenario-a/strategy-assignment).
### Versioning and changes
The API is versioned via its base URL. Breaking changes are announced in the [changelog](/dedicated-client-vaults/reference/public-api) and backwards-compatible additions are rolled out without notice — favour lenient parsing of response bodies.
# Audit Reports
Tesseract publishes independent audits of the smart contracts that back Dedicated Client Vaults.
### Tesseract Earn Vault
Tesseract Earn Vault is the underlying smart contract infrastructure, operated by Tesseract Investment Oy under its MiCA CASP authorisation for the DCV service. It has been independently audited by Omniscia and CertiK.
🔗 [Omniscia Audit Report — Tesseract Earn Vault](https://omniscia.io/reports/tesseract-earn-vault-69b81216873cc00015ff3fbf/)
🔗 [CertiK Security Assessment — Tesseract](https://skynet.certik.com/projects/tesseract)
### Underlying vault infrastructure
DCVs are deployed on top of vault infrastructure that has been separately audited upstream. Those reports are published by the infrastructure provider:
🔗 [IPOR Fusion — Security & Audits](https://docs.ipor.io/build-on-fusion/developer-guide/security-and-audits)
### Scope and limitations
Independent audits reduce but do not eliminate smart-contract risk. On-chain yield vaults involve significant risks including smart contract vulnerabilities, liquidity risk, oracle risk, and the risk of total loss of capital.
# FAQ
Frequently asked questions about Tesseract's Dedicated Client Vaults. For Earn Direct / Earn API questions, see [Earn Direct & Earn API → FAQ](/earn-direct-and-earn-api/faq).
### Product & structure
**What exactly am I buying?**
A MiCA-authorised discretionary portfolio management mandate operated by **Tesseract Investment Oy**, executed through per-client on-chain vaults. It is not software, not a fund, and not a wrapper — it is regulated asset management. Tesseract Investment Oy manages each vault individually under its MiCA CASP authorisation.
**Why isn't this just a wrapper around DeFi?**
Key structural differences: (1) each client gets their own dedicated vault contract — genuinely separate on-chain, not just accounting separation; (2) non-transferable share tokens avoid collective-investment-scheme and securities classification; (3) Tesseract Investment Oy holds a MiCA CASP authorisation covering portfolio management — most competitors do not. The moat is regulatory and structural, not just a product feature.
**How are DCVs genuinely segregated?**
Each client's assets sit in their own standalone smart contract at all times. Rebalancing and management happen at the individual vault level — assets never leave the vault to enter a shared pool. This is genuine segregation at the asset level.
**What is the minimum deposit for a vault?**
Approximately $50,000 USDC (or equivalent in WETH / WBTC). Current per-asset minimums are readable on-chain from each deployer — see [Contract Methods](/dedicated-client-vaults/reference/contract-methods).
**What assets are supported?**
USDC, WETH, and WBTC on Ethereum mainnet. See [Contract Addresses](/dedicated-client-vaults/reference/contract-addresses) for deployed vault-deployer addresses per asset.
**What yields can I expect?**
Indicative gross yields are approximately 5–6% (Conservative) and 8–12% (Advanced) for stablecoins (USDC), 4–6% for WETH, and 3–5% for WBTC. These are indicative and subject to market conditions. Past performance is not indicative of future results.
**What about fees?**
0.25% management fee on AUM and 30% performance fee on vault profits. No deposit or withdrawal fees. Fees are levied at the vault level and programmatically split. Partner revenue share under the Introducer / Distribution Agreement is agreed during partnership setup. See [Fees & Commercial Model](/dedicated-client-vaults/fees-and-commercial-model).
**What strategies are available?**
Current strategy options are visible in the [Tesseract app](https://app.tesseract.fi). Strategy selection is made at vault creation — see [Strategy Assignment](/dedicated-client-vaults/integration-guide/scenario-a/strategy-assignment).
**Will my clients know Tesseract exists?**
By default, the Tesseract brand is visible because clients interact via [app.tesseract.fi](https://app.tesseract.fi). For partners integrating DCVs into their own product, the direct smart-contract integration path lets your UI drive the full flow without the Tesseract app being involved — see [Integration Guide](/dedicated-client-vaults/integration-guide). Brand surface during onboarding depends on whether you embed the Compliance app (coming soon).
### Integration
**What does the first 30 days of integration look like?**
For a partnership (Scenario B): legal agreement and due diligence, KYB on your organization, credential provisioning, reporting integration, and acceptance testing. For direct client use (Scenario A): complete KYC / KYB, get whitelisted, deploy and test. See [Choose Your Scenario](/dedicated-client-vaults/integration-guide/choose-your-scenario).
**What does my end client actually do?**
Complete KYC / KYB, wait for wallet whitelisting, deploy a vault with an initial deposit, pick a strategy, and then track performance. See [Vault Lifecycle](/dedicated-client-vaults/vault-lifecycle).
**How do withdrawals work?**
Amounts covered by available liquidity withdraw instantly in a single transaction. Larger amounts use a three-step scheduled flow that spans up to \~24 hours. See [Instant Withdrawals](/dedicated-client-vaults/integration-guide/scenario-a/instant-withdrawals) and [Scheduled Withdrawals](/dedicated-client-vaults/integration-guide/scenario-a/scheduled-withdrawals).
**Can I use a multisig or MPC wallet to interact with the vault?**
Yes — and it's the recommended setup. Only the whitelisted wallet can deposit or withdraw, so it makes sense to whitelist a wallet that already carries your custody and approval controls — an MPC wallet (e.g. Fireblocks) or an on-chain multisig / smart account (e.g. Safe) — and reuse your existing multi-approval and transaction-policy setup. See [Roles & Access](/dedicated-client-vaults/roles-and-access).
**What happens during market stress?**
In calm markets withdrawals process quickly. During market stress, DeFi pool utilization can spike and temporarily slow scheduled-withdrawal processing while positions are unwound. Automated risk management proactively maintains liquidity, but instant withdrawals cannot be guaranteed in all market conditions.
### Compliance & legal
**Is this product specifically approved by FIN-FSA?**
Tesseract Investment Oy's MiCA CASP authorisation covers discretionary portfolio management of crypto assets. DCVs are structured as a permitted activity under that authorisation. DCVs are not regulated financial instruments and are not covered by investor compensation schemes.
**Who are the underlying DeFi counterparties?**
Tesseract provides transparency at the protocol level — only pre-approved, whitelisted DeFi protocols may be used. DeFi lending protocols are permissionless by design, meaning borrowers are pseudonymous wallet addresses rather than KYC'd entities. This is a consideration for regulated distributors with strict counterparty-transparency requirements.
**Who owns KYC / compliance responsibility?**
Depends on integration shape. Under Scenario A, the client is a direct Tesseract client and completes Tesseract KYC. Under Scenario B, responsibility is agreed in the partnership — Tesseract runs full KYC, the partner runs KYC under reliance, or a hybrid. See [Scenario B](/dedicated-client-vaults/integration-guide/scenario-b).
**Can Tesseract move client funds without consent?**
The standard deposit / withdraw interface is locked to the whitelisted client wallet. Tesseract Investment Oy executes the agreed discretionary mandate (rebalancing, risk management), with multisig governance and compliance oversight ensuring operations remain within mandate.
### Risk & accountability
**The underlying risk is still DeFi risk — why should my board care about the structure?**
The DCV structure changes three things: (1) **legal exposure** — designed to sit outside AIFMD and securities characterisation, with a non-custodial architecture; (2) **operational outcomes** — per-client segregation means one client's problem doesn't cascade; (3) **compliance coverage** — a MiCA-authorised portfolio management mandate. It does not eliminate underlying DeFi risk (smart contract, liquidity, oracle). The value is making DeFi yield distributable within a regulated framework.
**When something goes wrong, who is accountable?**
Tesseract Investment Oy is accountable as the regulated portfolio manager executing the discretionary mandate. The client retains ownership of their vault via the non-transferable share token. Custody-provider responsibilities (where applicable) follow the custody terms. Risk allocation is defined in the partnership agreement.
**What happens in the first 60 minutes after an exploit?**
Tesseract operates 24/7 automated risk management with auto-deleveraging when risk thresholds are breached, and an emergency compliance freeze for rapid response. The incident response process — named responders, partner notification, and SLAs — is defined in the partnership agreement.
**What can my risk team verify independently?**
On-chain: your auditor can independently verify vault balances, ownership tokens, and contract state on Ethereum mainnet using any block explorer. The non-transferable ERC‑4626 share token serves as cryptographic proof of ownership that requires no cooperation from Tesseract to verify.
**Can the strategy change without partner approval?**
Strategy changes within the agreed mandate are managed by Tesseract's portfolio management team as part of the discretionary service. Material changes to the strategy framework are governed by the change-control process defined in the partnership agreement.
# Earn Direct
> **Not for UK persons.** This website and its contents are not directed at persons located in, or resident in, the United Kingdom. They do not constitute a financial promotion within the meaning of section 21 of the Financial Services and Markets Act 2000, and are not approved by an authorised person.
Earn Direct provides institutional and professional clients with a secure route to earn yield on digital assets, under Tesseract Investment Oy's MiCA authorisation and with independent oversight. **Tesseract Investment Oy** operates the consumer experience, KYC/AML, custody, and asset transfers under its MiCA CASP authorisation. Partners refer users; Tesseract runs the consumer experience, compliance, and distribution. The underlying yield services (such as Institutional Lending) are provided by separate Tesseract entities and are outside the MiCA regulatory perimeter.
> **Note on custody architecture.** Earn Direct and DCV use different custody architectures. Earn Direct uses MiCA-authorised custody through Fireblocks MPC. DCV is non-custodial; the client's assets reside in their own dedicated vault contract.
**Key features:**
* MiCA-authorised compliance and custody under Tesseract Investment Oy. Institutional Lending is provided by Tesseract Earn Oy and its UK SPVs, applying equivalent governance and risk standards.
* User authentication
* KYC and onboarding
* Wallet connectivity
* Service selection and deposit flow
* Portfolio view and withdraw flow
* Customer support
**Key non-functional requirements:**
* Geoblocking for restricted usage
* Consumer data management and GDPR compliance
* ISO 27001 and SOC 2 certified technology platform (Tesseract Earn Oy)
**Try it yourself:** [private.earndirect.tesseractinvestment.com](https://private.earndirect.tesseractinvestment.com)
### Who it's for
Earn Direct serves three primary audiences — each addressed in its own section:
* [**Institutional Clients**](/earn-direct-and-earn-api/earn-direct/for-institutional-clients) — wallet providers, fintechs, exchanges, and brokerages that do not hold the relevant regulatory authorisations in their jurisdiction and partner with a regulated provider to offer yield services to their clients.
* [**Private Investors**](/earn-direct-and-earn-api/earn-direct/for-private-investors) — high-net-worth individuals and experienced crypto investors who want yield with full transparency and control.
* [**Treasury Management**](/earn-direct-and-earn-api/earn-direct/for-treasury-management) — DAOs, Web3 startups, crypto foundations, and enterprises holding crypto on their balance sheet.
***
> **Availability.** Tesseract Investment Oy does not provide services to persons in the United States, the United Kingdom, the United Arab Emirates, Japan, South Korea, Singapore or Australia. Service availability in other jurisdictions is subject to Tesseract's assessment of applicable regulatory and sanctions requirements.
***
*This website is a marketing communication of Tesseract Investment Oy, a crypto-asset service provider authorised under Regulation (EU) 2023/1114 (MiCA) by the Finnish Financial Supervisory Authority (FIN-FSA). It is directed at institutional counterparties under a non-disclosure agreement with Tesseract. It is not an offer or solicitation.*
# For Institutional Clients
Earn Direct is a service for institutional partners — including wallet providers, fintech platforms, crypto exchanges, and brokerage firms — that wish to partner with a regulated provider to offer yield services to their clients, rather than operate the regulatory infrastructure in-house.
**Tesseract Investment Oy** — MiCA-authorised and FIN-FSA-supervised as a Crypto Asset Service Provider — handles all KYC / AML, custody, and asset transfer requirements. Partners remain responsible for their own regulatory obligations, including any licensing, suitability and consumer-protection requirements applicable to them.
The model suits institutions that do not hold the relevant regulatory authorisations in their jurisdiction and want a compliant, scalable route to offer yield services to their clients through a regulated partnership.
Institutional clients operate on Earn Direct as an [organization](/earn-direct-and-earn-api/earn-direct/organizations) — a shared workspace for a team. See [Organizations](/earn-direct-and-earn-api/earn-direct/organizations) for onboarding, KYB, and shared wallets, and [Team Management](/earn-direct-and-earn-api/earn-direct/organizations/team-management) for inviting members, roles and permissions, and wallet verification.
# For Private Investors
Earn Direct provides an efficient and secure avenue for high-net-worth individuals and experienced crypto investors to earn passive yield on their digital assets.
The platform is designed with transparency and control in mind, giving users full visibility into performance, risk, and yield generation while benefiting from Tesseract's institutional-grade custody and risk management. This audience values the ability to retain direct access to their assets and operate independently, while relying on **Tesseract Investment Oy** — MiCA-authorised and FIN-FSA-supervised — to handle KYC/AML, custody, and asset transfers without the complexity of managing them manually.
The result is a high-trust, user-friendly service that blends autonomy with professional oversight.
# For Treasury Management
For companies holding crypto on their balance sheets — such as DAOs, Web3 startups, crypto foundations, or enterprises exposed to digital assets — Earn Direct functions as an enterprise-grade treasury management tool.
The platform allows these organizations to generate yield on dormant assets daily through an interface designed for straightforward adoption, liquidity flexibility, and clear operational visibility.
Financial teams gain access to ongoing insights regarding earnings and account positions, adjustable governance structures, and integrated reporting capabilities compatible with existing accounting infrastructure. The system supports compliance preparation and regulatory adherence by furnishing downloadable transaction records, establishing documented verification suitable for financial review and regulatory documentation.
The offering transforms otherwise inactive crypto holdings into productive financial resources within a framework emphasising user control, regulatory alignment, and institutional-grade administration.
Treasury teams operate on Earn Direct as an [organization](/earn-direct-and-earn-api/earn-direct/organizations) — a shared workspace with role-based access. See [Organizations](/earn-direct-and-earn-api/earn-direct/organizations) for onboarding, KYB, and shared wallets, and [Team Management](/earn-direct-and-earn-api/earn-direct/organizations/team-management) for inviting members, roles and permissions, and wallet verification.
# Organizations
Institutional clients use Earn Direct as an **organization** — a single workspace shared by a team. Deposits, withdrawals, portfolio, and reporting are scoped to the organization, so every member sees the same balances and activity.
### Onboarding & verification
The first person to log in from a partner organization is provisioned as the organization **admin** with full permissions. The organization starts in a `pending verification` state and must complete **KYB (Know Your Business)** verification before it can deposit or withdraw.
KYB is performed once per organization, not per individual. The admin initiates verification; on approval, the organization becomes `active` and every member is cleared to transact — team members do not complete individual KYC.
### Shared deposit wallets
Deposit addresses are shared across the organization at the product level. The first member to deposit into a product provisions the wallet; every other member deposits to the same address. This keeps custody consolidated rather than fragmenting funds across per-user wallets.
Interest accrues on the organization's net pooled balance per product and is reported as a single daily entry per product.
### Activity log
Every management action — invites, role changes, suspensions, KYB, and wallet verification — is recorded in an audit trail visible to the organization under the **Activity** tab.
### Organization status
| Status | Meaning |
| ---------------------- | -------------------------------------------------- |
| `pending verification` | Created, awaiting KYB. Cannot deposit or withdraw. |
| `active` | KYB approved. Full access for all members. |
| `suspended` | Access revoked. |
### Managing the team
See [Team Management](/earn-direct-and-earn-api/earn-direct/organizations/team-management) for inviting members, roles and permissions, and wallet verification.
### Managing wallets
See [Managing Whitelisted Wallets](/earn-direct-and-earn-api/earn-direct/organizations/managing-whitelisted-wallets) for changing a product's withdrawal address and retiring (deactivating) a deposit wallet — both client-requested and Tesseract-approved.
# Team Management
Admins manage their [organization's](/earn-direct-and-earn-api/earn-direct/organizations) team — inviting members, assigning roles, and controlling access.
### Inviting members
Admins invite members by email. The invitee receives a link, authenticates, and joins the organization with the role chosen at invite time. Invites expire after **7 days** and can be revoked or resent. Membership is always explicit — there is no email-domain auto-join.
If the organization is already `active`, invited members are cleared to transact as soon as they accept.
### Roles & permissions
Every member has exactly one role, and permissions derive from that role.
| Role | What they can do |
| ------------------------ | ------------------------------------------------------------------- |
| **Admin** | Full control — manage the team, run KYB, and perform all operations |
| **Withdrawals Manager** | Create deposits and submit withdrawals |
| **Whitelisting Manager** | Whitelist withdrawal addresses and create deposits |
| **Viewer** | Read-only access to portfolio, reports, and activity |
Key boundaries:
* Only **admins** invite members, change roles, suspend members, and run KYB.
* Verifying (whitelisting) an address requires the **Whitelisting Manager** (or admin) role.
* Submitting a withdrawal requires the **Withdrawals Manager** (or admin) role.
* The two manager roles are separate: a Whitelisting Manager cannot submit withdrawals, and a Withdrawals Manager cannot verify addresses. Both can create deposits.
### Member lifecycle
Admins can change a member's role or **suspend** a member; suspension takes effect on the member's next request and can be reversed by reactivating them. Admins can also change another admin's role — including downgrading an admin to a more restrictive role. Admins cannot suspend themselves or change their own role.
### Wallet verification
Before the organization can withdraw to an external address, that address must be **verified** (whitelisted). A **Whitelisting Manager** or admin submits the address; it is screened through Tesseract's compliance checks (travel rule and wallet risk screening) and becomes available for withdrawals once approved. Until then it stays on hold. Verified addresses are shared across the organization.
Once verified, wallets can be managed — changing which wallet receives a product's withdrawals (**Admin**-only), or retiring one you no longer use (**Whitelisting Manager** or **Admin**). See [Managing Whitelisted Wallets](/earn-direct-and-earn-api/earn-direct/organizations/managing-whitelisted-wallets).
# Managing Whitelisted Wallets
Once an address is [verified](/earn-direct-and-earn-api/earn-direct/organizations/team-management#wallet-verification), your [organization](/earn-direct-and-earn-api/earn-direct/organizations) can manage it from **Profile → Whitelisted Wallets** — change which wallet receives a product's withdrawals, or retire a deposit wallet you no longer use.
Both actions are **requested by the client and approved by Tesseract**. Nothing changes silently: a request stays pending until a Tesseract operator actions it, so a payout address can't be redirected — and a wallet can't be retired — without that review.
> Who can do what: changing a product's **withdrawal address** — and cancelling such a request — is **Admin-only**. **Deactivating a deposit wallet** (and cancelling a pending deactivation) can be done by a **Whitelisting Manager** or an **Admin**. See [Team Management](/earn-direct-and-earn-api/earn-direct/organizations/team-management).
### Wallet states
Each wallet in the list shows its state as colour-coded tags:
| Tag | Meaning |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| **Deposit** | Whitelisted and deposited from — usable for deposits. |
| **Withdrawal** | The product's current payout address. Each product has exactly one at any time. |
| **Pending** | A change or deactivation for this wallet is awaiting Tesseract approval. |
| **Inactive** | The wallet has been deactivated. It stays listed as a record and can be brought back by re-verifying it. |
A wallet can be both **Deposit** and **Withdrawal** — a product's payout address always starts as a wallet you've deposited from.
## Changing a product's withdrawal address
By default, a product pays out to the first wallet you whitelisted and deposited from. To route withdrawals elsewhere:
1. Open **Whitelisted Wallets** and choose **Change withdrawal address** on the product.
2. Pick the new address. Only wallets you have **already whitelisted and deposited from** are offered — there is no free-text address entry, and the current payout address isn't selectable.
3. Submit. The request enters a **Pending** state and appears for Tesseract operators to review.
The change only takes effect once Tesseract approves it. Until then:
* The **current** payout address stays active — withdrawals already made are unaffected.
* **New withdrawals for that product are paused** and can't be started, with a notice explaining why. Other products are unaffected — holds are per product.
* Any **Admin** in the organization can **cancel** the pending request at any time before it's actioned; the current address stays in place and the hold releases.
If Tesseract can't confirm the new address, the operator **rejects** the request — the current address is kept and the hold releases. On approval, the **Withdrawal** tag moves to the new wallet and future withdrawals for that product route there.
> A change can't be requested for a product that already has a withdrawal in progress — wait until it settles.
## Deactivating a deposit wallet
To retire a deposit wallet you no longer use, choose **Deactivate wallet** on it.
Deactivation is **not immediate** and is **not a deletion**. It creates a pending request that a Tesseract operator confirms out-of-band. While pending, the wallet keeps working for deposits. On confirmation:
* The wallet is marked **Inactive** — its **Deposit** tag is replaced.
* It **stays visible** in the list as a historical record.
* Later deposits from it are quarantined for review rather than credited automatically.
A wallet **can't be deactivated** while it is a product's active withdrawal address, or while it's the target of a pending withdrawal-address change. To retire a wallet that is also a payout address, first change that product's withdrawal address away from it, then deactivate it.
To use an inactive wallet again, simply **re-verify** it (deposit → verification link → confirm ownership). Completing verification restores its **Deposit** tag — there is no separate "reactivate" step.
## Approvals & timing
Because Earn Direct payouts are controlled by Tesseract, approval sits on the Tesseract side. Operators action requests after completing the required compliance checks (including the Sumsub / Fireblocks steps that can't be automated), so a request may sit **Pending** briefly — for example over a weekend when no operator is available. This is expected and keeps the control step evidenced rather than automatic.
### Activity log
Every step — requested, approved / effective, rejected, cancelled, and wallet deactivations — is recorded in the organization's **Activity** tab, showing who did what, when, and the outcome (including the old → new address for changes). See [Organizations → Activity log](/earn-direct-and-earn-api/earn-direct/organizations#activity-log).
# Troubleshooting
Common issues and resolutions for Earn Direct. If you cannot resolve an issue using this guide, contact .
***
## Invites
**The invitee did not receive the invitation email**
Check the invitee's spam or junk folder first. If the email is not there, an Admin can resend the invite from the **Users Management** tab by locating the pending invite and selecting **Resend**. Invites expire after **7 days** — if the original invite has expired, revoke it and send a new one. Ensure the email address entered at invite time was correct.
**The invite link shows "Invitation unavailable"**
This means the invite has either expired (invites are valid for 7 days) or has already been revoked by an Admin. Ask an Admin to resend or reissue the invitation. If the invitee clicks an old link saved in their email client, the same error will appear even after a new invite has been sent — they should use the most recent invitation email.
**The invitee sees an error on redemption: "already belongs to another organization"**
Each user account can belong to only one organization. If the invitee already has an account associated with a different organization, they cannot join a second one using the same account. The invitee should contact to clarify whether a separate account can be created, or whether their existing organization membership should be changed.
**The invitee successfully signed up but cannot see the Users Management tab**
The **Users Management** tab is visible only to **Admins**. If the invitee was assigned a non-Admin role (Withdrawals Manager, Whitelisting Manager, or Viewer), the tab will not appear in their navigation. An Admin can update the member's role from the **Users Management** tab if broader access is required.
**An Admin cannot invite a user who is already in the organization**
A user who is already an active or suspended member of the organization cannot be re-invited — they are already in the member list. To restore access for a suspended member, locate them in the **Users Management** tab and select **Reactivate**. If the user was removed and needs to rejoin, contact .
***
## KYB Verification
**The "Verify" button is not visible**
The **Verify** button is shown only to **Admins** when the organization is in `pending verification` status. If you do not see it, check that:
1. You are logged in as an Admin (non-Admin roles cannot initiate KYB).
2. The organization has not already completed or is currently undergoing verification — check the organization status indicator.
If the status shows `active`, KYB has already been approved and no further action is needed.
**The Sumsub KYB flow does not open or shows an error**
Sumsub's verification widget requires a stable internet connection and a supported browser (latest versions of Chrome, Firefox, Safari, or Edge). Try the following:
1. Disable browser extensions, particularly ad-blockers or privacy shields that may block third-party scripts.
2. Try a different browser or an incognito/private window.
3. Ensure your network does not block third-party cookies or the `sumsub.com` domain.
If the issue persists, contact with your browser version and a description of the error shown.
**KYB verification has been submitted but the organization status has not updated**
After submission, KYB review typically completes within **1–2 business days**. The organization status will update to `active` automatically once approved. If more than 2 business days have passed without an update, contact and include your organization name and the date of submission.
**KYB was approved but some users are still showing as unverified**
KYB verification is at the **organization level**, not the individual level. Once the organization reaches `active` status, all current members are cleared to transact — individual member verification is not required. If a user is still restricted, check whether they have accepted their invite and are an active member (not pending). Members who accept an invite after KYB approval are also immediately cleared.
***
## Withdrawal Approvals
**A withdrawal has been in "pending approval" status for an extended period**
Withdrawals require approval from a user with the **Withdrawals Manager** or **Admin** role. If no eligible approver has acted, contact your organization's Admin to review and approve or reject the pending withdrawal. If the intended approver is unavailable or the organization has no active approver, contact .
**A withdrawal was rejected. How do I resubmit?**
A rejected withdrawal cannot be modified — it must be resubmitted as a new request. Navigate to the **Portfolio** tab, select the relevant asset, and initiate a new withdrawal. If you are unsure why the original withdrawal was rejected, check the **Activity** tab for a rejection note, or contact your organization's Admin.
**The Withdraw button is not visible in the portfolio**
The **Withdraw** button is only available when:
1. Your role is **Withdrawals Manager** or **Admin**.
2. The organization status is `active` (KYB approved).
3. There is a positive balance available for the selected asset.
4. At least one verified (whitelisted) withdrawal wallet exists.
If all conditions are met and the button is still not visible, try refreshing the page. If the issue persists, contact .
***
## Wallet Whitelisting
**A wallet shows "Verify Wallet" but the verification link does not open**
The verification link launches an external compliance check. Ensure your browser allows pop-ups from the Earn Direct domain, or copy the link and open it in a new tab. If the link fails to load, try a different browser or disable browser extensions that may block outbound links. If the problem continues, contact with the wallet address and a description of the error.
**The wallet status has not updated after completing verification**
After completing the verification flow, the wallet undergoes compliance screening (travel rule and wallet risk screening). This process can take up to **1 business day**. The wallet will move from `pending` to an approved or rejected state once screening completes. If status has not changed after 1 business day, contact with the wallet address in question.
**A deposit wallet is not appearing in the Wallets tab**
Deposit wallets are provisioned when the first deposit is made into a product. If no member of your organization has yet deposited into that product, no deposit wallet will be shown. Once an initial deposit is submitted, the wallet address will appear in the **Wallets** tab. If you have already deposited and the address is still missing, refresh the page; if it does not appear, contact .
***
## Roles & Permissions
**A user's role was changed but their permissions have not updated**
Permission changes take effect on the member's **next authenticated request** after the change is applied. In practice this means the updated permissions may take up to **5 minutes** to reflect on an active session. Ask the affected user to log out and log back in to force an immediate refresh of their session state.
**An Admin cannot change another Admin's role**
Admins can change the role of any other Admin — including downgrading them to a more restrictive role. However, an Admin **cannot change their own role**. If the role change is not going through, verify you are attempting to change a different user's role, not your own. If the target user is the organization's only Admin, contact for assistance.
**A user was suspended but can still access the platform**
Suspension takes effect on the member's **next request** following the suspension action and may take up to **5 minutes** to propagate to an active session. If the suspended user still has access after this window, contact immediately with the user's email address and the time of suspension.
***
## Activity Tab
**An expected event is not appearing in the Activity tab**
The **Activity** tab records management actions: invites, role changes, suspensions, KYB submissions and outcomes, and wallet verifications. Financial transactions (deposits, withdrawals, interest) appear in the **Portfolio** and **Reports** sections rather than the Activity tab. If an expected management event is missing, allow a few minutes for the event to be indexed, then refresh. If it is still absent, contact .
**The Activity tab is visible to all users — is that expected?**
Yes. The **Activity** tab is visible to all organization members regardless of role. Every member can see the organization's audit trail — invites, role changes, KYB events, and wallet verifications. This is by design to support transparency within the team. Only management actions are recorded; individual financial activity is not exposed here.
***
## Contacting Support
If this guide does not resolve your issue, contact Tesseract support at .
To help us resolve your issue as quickly as possible, include the following in your message:
* **Organization name** as it appears in Earn Direct
* **Your email address** (the one associated with your Earn Direct account)
* **Description of the issue** — what you were trying to do and what happened instead
* **Steps already taken** — what you have already tried based on this guide
* **Screenshots or error messages** — attach any relevant screenshots or copy the full text of any error messages displayed
* **Date and time** the issue occurred (including timezone)
For withdrawal or wallet issues, also include:
* The **asset** (e.g. USDC, WBTC)
* The **amount** involved
* The **wallet address** (for whitelisting issues)
{% hint style="info" %}
Tesseract Investment Oy is a MiCA-regulated crypto-asset service provider (CASP) authorised by the Finnish Financial Supervisory Authority (FIN-FSA). Earn Direct is available only in jurisdictions where Tesseract is permitted to operate. Access may be restricted in certain countries or regions in accordance with applicable law.
{% endhint %}
# Earn API
Earn API lets partners embed Tesseract yield directly into their own product. Your backend books deposits and withdrawals against Tesseract's accounting system, settles outstanding balances once per day per currency, and pulls daily reports to sync interest to user accounts.
This section covers the integration as a partner engineer would approach it:
* [**Overview**](/earn-direct-and-earn-api/earn-api/overview) — the two deliverables of a successful integration (deposit/withdrawal integration + daily settlement).
* [**Calculating Interest**](/earn-direct-and-earn-api/earn-api/calculating-interest) — how interest accrues, when it's distributed, the compounding formula, and worked examples.
* [**Settlements**](/earn-direct-and-earn-api/earn-api/settlements) — how netted per-currency daily settlements work and how to read the outstanding balance.
* [**Solution Architecture**](/earn-direct-and-earn-api/earn-api/solution-architecture) — the eight integration tasks and dependencies.
* [**Data Model Mapping**](/earn-direct-and-earn-api/earn-api/data-model-mapping) — how to map your users / accounts to Tesseract's data model when you receive two credential sets, one per product line.
* [**Process and Environments**](/earn-direct-and-earn-api/earn-api/process-and-environments) — Development / Test / Production environments and the end-to-end integration process.
* [**Acceptance Testing**](/earn-direct-and-earn-api/earn-api/acceptance-testing) — test cases run in Production before go-live.
* [**Working with Reports**](/earn-direct-and-earn-api/working-with-reports) — daily reports published by the accounting cycle and their schema.
Interactive API reference: [earn-api.partner.env.tesseractinvestment.dev/docs](https://earn-api.partner.env.tesseractinvestment.dev/docs/)
**Estimated integration time:** 14–21 days.
# Overview
Earn API is designed for businesses that want to offer crypto-earning opportunities to their customers without the complexity of managing the backend infrastructure. It provides a straightforward integration process that allows companies to incorporate yield-generating features into their existing platforms. The API handles all the technical details — wallet management, security, and compliance — enabling businesses to focus on their customer experience while offering competitive returns on crypto assets.
This solution is ideal for crypto exchanges, fintech companies, and any service provider looking to expand into the cryptocurrency earning space.
### Integration
From a partner perspective, a successful Earn API integration has two elements that need to be completed:
1. **Deposit and withdrawal integration.** Earn API provides endpoints to let the partner present Tesseract's products to end users and book deposits and withdrawals into Tesseract's accounting system.
2. **Daily settlement integration.** Crypto transactions to settle the outstanding balance between partner and Tesseract happen on a daily basis. Earn API report endpoints provide clear figures for amounts to settle as well as complete visibility into Tesseract's accounting system for partners to verify correctness.
These two elements are broken down in [Solution Architecture](/earn-direct-and-earn-api/earn-api/solution-architecture).
# Calculating Interest
### Distribution
#### How is it calculated?
Accounts accrue interest inherited from the Product configuration and include a configurable user interest rate plus an optional partner margin. Interest is distributed to accounts every day using a compounding interest formula based on end-of-day account balances.
The accrual process involves:
* Interest distribution to accounts.
* Partner margin accrual (optional, defined per Product / currency).
Daily settlement occurs between the partner and Tesseract for outstanding balances.
**Example use case 1:** Partners integrate Tesseract's platform to enable customers to deposit capital into interest-earning accounts.
**Example use case 2:** Partners with available capital but no direct customers can issue a single per-currency account and optionally include partner margin.
#### When is interest distributed to an account?
Interest is distributed to accounts once an accounting day (also known as an accounting cycle) has ended. The accounting cycle runs from 00:00:00–23:59:59 in the partner's timezone. Interest distributes shortly after 00:00:00 the following day. Deposits or withdrawals during any day affect the balance used for interest calculation.
**Example 1** — user earning interest on initial deposit (3.5% APY account):
* Day 1: user deposits 1 BTC (balance: 1 BTC).
* Day 2: user receives Day 1 interest; balance becomes 1.00009425493 BTC.
**Example 2** — user withdrawing entire balance:
* Day 2: user withdraws 1.00009425493 BTC.
* Day 3: no interest accrues (balance at Day 2 end was zero).
**Note on edge cases:** deposits made just before interest distribution still earn interest that day, balanced by withdrawals earning no interest on withdrawn amounts.
### Compounding interest formula
Interest calculation uses a compounding APY method based on total account balance at the previous accounting cycle's end:
```
user_balance(t) * [(1 + interest_rate)^(1/365) - 1]
```
**Example — account with 0.5 BTC**
Day 1 — user deposits 0.5 BTC to a "Basic BTC interest account" with the 3% tier (0–1 BTC balance) and no partner margin. Account balance: 0.5 BTC.
Day 2 — interest calculation:
```
0.5 * ((1 + 0.03)^(1/365) - 1) = 0.50004049 BTC
(earned: 0.00004049 BTC)
```
Day 3:
```
0.50004049 + (0.50004049 * ((1 + 0.03)^(1/365) - 1)) = 0.50008099 BTC
```
Day 4:
```
0.50008099 + (0.50008099 * ((1 + 0.03)^(1/365) - 1)) = 0.500121489 BTC
```
# Settlements
### How it works
When Earn API is used to deposit and withdraw assets to accounts, no actual transfers are sent or received. Instead, all deposits and withdrawals per accounting cycle are netted and added to a per-currency outstanding balance.
The outstanding balance represents an unsettled balance that is expected to be sent or received as per the agreements for settlement intervals (typically daily).
If the total amount to be settled is less than the **minimum settlement threshold**, the outstanding balance will remain 0 and no transactions need to be done.
### Settlement flow
At midnight (partner's timezone) the current accounting cycle ends. Tesseract produces a settlement update based on the outstanding balance using the following steps:
1. Calculate the accrued balances since the last settlement:
* **Accrued payables** = accrued deposits + accrued fees (what the partner is to pay to Tesseract).
* **Accrued receivables** = accrued withdrawals + accrued partner margin (what Tesseract is to pay to the partner).
2. Net accrued payables and receivables by subtracting one from the other (**accrued receivables − accrued payables**).
* If the netted balance is less than the minimum settlement amount, no settlement is created and the outstanding balance is not updated.
* If the netted balance is greater than or equal to the minimum settlement amount, a settlement is created and the outstanding balance is updated by adding the netted payables and receivables.
Every day (or at regular intervals), the partner and Tesseract each check the outstanding balance per currency using the [API](https://earn-api.partner.env.tesseractinvestment.dev/docs/) to determine who sends assets to the counter-party:
* **Positive balance** — Tesseract sends capital to the partner; expect to receive a certain amount within the day (times may vary depending on amount).
* **Negative balance** — the partner sends the given currency to Tesseract. When the transaction is received, the outstanding balance is updated.
### Benefits of this process
1. All deposits and withdrawals are batched — only one transaction per currency per day is exchanged. This makes the exchange of assets predictable and less error-prone.
2. Saves on fees — one transaction per day means smaller total network costs, combined with small amounts below the minimum settlement threshold waiting to be settled until later.
3. If too little or too much is sent from partner to Tesseract (or vice versa), the outstanding balance updates accordingly and is taken into account in the next settlement.
### Minimum settlement amount
The minimum settlement amount ensures small amounts aren't settled. Typically the minimum settlement amount is set to a value equivalent to 1,000 USD per currency, but it may be updated dynamically to suit specific needs.
### Balances
The following terms describe the day-to-day settlement process of the outstanding balance:
* **Outstanding balance** — amount per currency exposed by the API, indicating who is to send money. Negative means the partner owes Tesseract; positive means Tesseract owes the partner.
* **Accrued payables** — amount per currency the partner is currently accruing to pay to Tesseract when a new outstanding balance is calculated.
* **Accrued receivables** — amount per currency the partner is to receive from Tesseract when the outstanding balance is calculated.
* **Netted accrued payables and receivables** — the netted accrued payables and receivables used to update the outstanding balance.
# Solution Architecture
Earn API is engineered for straightforward integration across custodian systems. This overview outlines integration partner responsibilities without requiring knowledge of your specific architecture.
### Integration tasks overview
The solution involves eight key tasks. Synchronous operations occur alongside user interface actions; asynchronous operations run as background jobs.
| # | Task | Description | Dependencies |
| - | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------ |
| 1 | Authentication | OAuth2 Client Credentials Flow (M2M) is used to acquire an access token for Earn API. | — |
| 2 | Product list | Partners retrieve product listings from internal storage, with options for automated sync or manual database maintenance. | 1 |
| 3 | Create Tesseract user and accounts | User and account creation before deposits, implementable synchronously at deposit time or beforehand. | 1, 2 |
| 4 | Deposit | Partner calls Earn API to book a user deposit into Tesseract's accounting with no immediate crypto transfer. | 1, 3 |
| 5 | Balance and transaction views | Balance and transaction details sourced from partner systems. | 4b, 6b, 8 |
| 6 | Withdrawal | Partner books a withdrawal on Earn API with no immediate crypto transfer. | 1, 4 |
| 7 | Daily settlement | Partners fetch daily reports containing settlement figures and initiate crypto transactions where deposits exceed withdrawals. | 1 |
| 8 | Daily interest sync | The daily report contains all journal entries for the day, requiring partner synchronisation. | 1 |
### Accounting cycle
The accounting cycle executes daily at 00:00 (typically UTC) and handles user interest distribution, partner margin allocation, and report generation.
### Daily settlement process
When Earn API is used to deposit and withdraw assets to accounts, no actual crypto transfers are sent or received. Instead, all deposits and withdrawals are netted per-currency once per day. Partners configure wallet addresses within Earn API for automated settlement, with complete visibility through daily reports.
### Multi-entity compliance structure
Partners receive separate authentication credentials for each product line due to regulatory requirements. Partners must maintain credential-to-user mappings and create dual Earn API user accounts per end user while presenting a unified product experience. See [Data Model Mapping](/earn-direct-and-earn-api/earn-api/data-model-mapping) for the mapping pattern.
# Data Model Mapping
At the start of an integration project, Tesseract delivers two sets of credentials. Both are necessary to make the available yield products accessible to end users. Different credentials are required to access each product type and their associated accounts.
The data structure on the Earn API side is straightforward. Each user maintains multiple accounts for storing transactions linked to a specific product. The key consideration is that your data model and code must support mapping to Earn API access using multiple credential sets.
### Example: product list
The product list displayed for your end users is the union of two calls to `GET /v1/products` — one with each credential set.
### Example: creating users
When establishing end users on your platform, you should create two users on Earn API by invoking `POST /v1/users` with the appropriate credential set for each product line. Store the user IDs from responses along with mappings to your end users — these mappings are essential for subsequent operations like account creation.
### Example: partner data model
Design specifics depend on partner requirements. A reference DBML schema is provided as part of integration onboarding and can be imported into online visualization tools to view table relationships and comments.
Typical tables include:
* `tesseract_product_types` — product taxonomy snapshot.
* `tesseract_products` — product catalogue snapshot synced from Earn API.
* `partner_users` — your own user records.
* `tesseract_users` — the two Tesseract user IDs per partner user (one per credential set).
* `tesseract_user_accounts` — per-product / per-currency accounts.
* `tesseract_user_account_transactions` — transaction log for reconciliation.
* `tesseract_wallets` — settlement wallet addresses.
* `tesseract_reports_processed` — tracking for idempotent daily report ingestion.
# Process and Environments
Our goal is to give you all the support you need throughout the integration. This page sets expectations for what to expect during the integration process.
### Environments
| Environment | URL | Description |
| ----------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Development | [earn-api-dev.partner.env.tesseractinvestment.dev](https://earn-api-dev.partner.env.tesseractinvestment.dev/) | Environment to develop against. All APIs are available but Tesseract does not settle its side of the outstanding balance. |
| Test | [earn-api-test.partner.env.tesseractinvestment.dev](https://earn-api-test.partner.env.tesseractinvestment.dev/) | Copy of production where the partner can develop and test daily settlement with small amounts of real crypto (no test net support). Product list is a subset of production. |
| Production | [earn-api.tesseractinvestment.com](https://earn-api.tesseractinvestment.com/) | Live partner integration. |
### Process
#### Intro call
The purpose of the call is to get the project started on the right foot. Topics typically covered:
* Walk through the integration process and developer site contents.
* Address questions raised while reading the documentation.
* Agree on the communication channel between engineering teams.
* Agree on the practicalities of authentication credential delivery and exchange of settlement wallet addresses.
* Discuss integration timeline.
Prerequisite: a mutual NDA has been signed.
#### Authentication credentials delivery
Authentication credentials are delivered to partners using Bitwarden Send. Recipients should store credentials in a password manager or similar. Development credentials can be used from developer workstations; Test and Production credentials should only be used in cloud-based systems.
#### Exchange of settlement wallet addresses
Both parties need a wallet address per currency for outstanding-balance settlement in Test and Production. Tesseract sends Test environment addresses as soon as development has started. Tesseract can finalize Test configuration once the partner's wallet addresses are received.
#### Gate to production
Once all tasks in [Solution Architecture](/earn-direct-and-earn-api/earn-api/solution-architecture) are done, the partner should test in the Test environment. Tesseract can help verify reception of assets and check report contents. Once the partner believes testing is complete, Tesseract performs a final check before preparing access to Production.
Authentication credential delivery and wallet address exchange happen the same way as for Test.
Prerequisite for production access: an Alliance Agreement is signed.
#### Acceptance test
Acceptance tests are done in the Production system to verify a solid integration and correct configuration of the wallet addresses on both sides. See [Acceptance Testing](/earn-direct-and-earn-api/earn-api/acceptance-testing) for details.
#### Go-live
The service can be opened as soon as the acceptance test result is satisfactory for both parties.
# Acceptance Testing
The Earn API integration acceptance testing ensures that both the user interface and backend financial transactions are functioning correctly. It evaluates essential functionalities including account creation, product access, deposits, withdrawals, and balance and transaction visibility. It also tests the integrity of settlement processes and wallet configurations to ensure accurate and efficient financial interactions between the partner and Tesseract.
These tests are performed directly in Production.
### TC\_1: User Journey Test
**Objective.** Verify that the user can access and interact with all selected Lending products through Earn API — ensuring that account creation, deposit, withdrawal, and balance views all function as expected within the integration.
**Key steps:**
1. **Creation of a new user and access to products.** Ensure new users can see and access all available Tesseract products.
2. **Deposit.** Test the deposit function for Lending products.
3. **View balances.** Check that the user's balance updates correctly after deposits.
4. **View transactions.** Ensure the user can view their transaction history for both deposits and any accrued interest.
5. **Withdraw funds.** Confirm that withdrawals are processed correctly and balances update accordingly.
### TC\_2: Settlement Test
**Objective.** Assess the accuracy and efficiency of settlement transfers between the partner and Tesseract — verifying that all financial transactions related to settlements are handled correctly and that wallet configurations are set up properly.
**Key steps:**
1. **Deposit across all products.** Test the deposit functionality by ensuring the partner owes Tesseract for all currencies, simulating a real-world load on the system.
2. **Observe Day 1 Earn API reports.** Check the reports for any discrepancies in the recorded transactions and ensure that all expected outbound transfers to Tesseract are successful.
3. **Withdraw funds and observe Day 2 reports.** After ensuring all funds are deposited, test the withdrawal to simulate Tesseract owing the partner. Verify the next day's reports to ensure all inbound transfers to the partner's wallets are successful.
# Working with Reports
As part of the daily accounting cycle, Earn API publishes reports. Partners need to access reports to sync interest transactions and to implement automated daily settlements.
Access reports with the following steps:
1. Get the list of available reports by calling `GET /v1/reports?type=Report`.
2. If new reports are available, call `GET /v1/reports/{reportId}/download-uri`.
3. Download the report from the URL returned in step 2.
> **⚠️ Deprecation notice.** `FullTransactionJournal` and `IncrementalTransactionJournal` report types are deprecated and will be removed in future releases. Always request the report list using `GET /v1/reports?type=Report`.
### Daily settlements
As part of the integration process, Tesseract and the partner exchange wallet addresses for each currency. The partner is expected to transfer the outstanding balance every day to the wallet addresses received from Tesseract. Tesseract likewise settles daily to the wallet addresses received from the partner.
Visibility into the direction and amount of the outstanding balance and the expected crypto transfer is available in the daily report per currency under `balances[].outstandingBalance`. The direction depends on the sign: a **negative** value means the partner is to settle towards Tesseract.
For example, if Tesseract owes `32.532298176173658034 BTC` to the partner and the partner owes `48.399149760390872272 SOL` to Tesseract, the corresponding settlements are expected to happen within the next day.
### Transaction sync
An important function of the accounting cycle is to distribute interest to all user accounts. Distributed interest entries are available in the report under the `transactions[]` array with `type === "Interest"`. Partners are expected to sync these entries for displaying to end users and for calculating per-account balances.
Example interest entry:
```json
{
"id": "d5266ad5-b724-4fce-9de0-27505317881d",
"type": "Interest",
"currency": "XRP",
"amount": "0.000000173182690071",
"createdAt": "2025-03-19T00:01:55.703Z",
"accountingDate": "2025-03-19T00:00:00.000Z",
"meta": {
"productId": "d09f17ff-d527-42e6-8876-83af2fe56df6",
"productName": "XRP Lending",
"accountType": "user",
"accountId": "3a7a9fa9-e6ca-4bf6-b563-ed58cb5d9cbf",
"groupId": "0ab365dd-4fea-4c53-a2fb-65287ae97725",
"userId": "c5640ae3-1b4b-41b0-b63a-6ea58da3fdd7"
}
}
```
### Example reports
Reports are available in all environments. The easiest way to get examples is to do some deposits in Development or Test and download real reports from Earn API.
### Report schema
The JSON report contains the following fields:
1. **`id`** — UUID of the report.
2. **`partnerId`** — UUID of the partner.
3. **`type`** — the type of the report (`"Report"`).
4. **`dateFrom`** — start date of the accounting cycle in UTC+0 ISO date format.
5. **`dateTo`** — end date of the accounting cycle in UTC+0 ISO date format.
6. **`balances`** — list of balance objects per currency:
* `currency` — Tesseract currency symbol.
* `outstandingBalance` — balance to be settled after the minimum settlement amount has been taken into account.
* `outstandingTotal` — the complete outstanding balance.
* `accruedReceivables` — accrued receivables (partner perspective).
* `accruedPayables` — accrued payables (partner perspective).
* `accountsReceivables` — accounts receivables (partner perspective).
* `accountsPayables` — accounts payables (partner perspective).
7. **`settlements`** — list of settlement objects per currency:
* `id` — UUID of the settlement.
* `createdAt` — UTC+0 ISO date of settlement creation.
* `currency` — Tesseract currency symbol.
* `transactionIds` — UUIDs of transactions associated with the settlement.
8. **`products`** — snapshot list of product objects:
* `id`, `group`, `name`, `currency`.
* `calculationMethod` — e.g. Fixed, Variable.
* `fixedInterestRate` — string representation (e.g. `"0.01"` = 1% APR or APY).
* `rateType` — APR or APY.
* `withdrawalPeriodDays`.
* `tiers` — array of `{ id, lowerBound, userInterestRate }`.
9. **`aum`** — AUM balance objects per product (deposits, withdrawals, interest, corrections, total amount).
10. **`transactions`** — list of transaction objects:
* `id`, `type`, `currency`, `amount` (18-decimal string).
* `createdAt`, `accountingDate` — UTC+0 ISO dates.
* `meta` — metadata object whose properties vary by transaction type.
#### Transaction types
**User accounts:**
* `Deposit` — deposit to an account.
* `Withdrawal` — withdrawal from an account.
* `Interest` — interest distributed to an account.
* `NegativeInterest` — negative interest distributed to an account.
* `Margin` — margin distributed to an account.
* `Fee` — fees distributed to the account.
**Partner account:**
* `SettlementIn` / `SettlementOut` — requested settlement booked to outstanding balances.
* `TransferIn` / `TransferOut` — money recorded as received in the outstanding balances account.
**Corrections:**
* `DepositCorrection`, `InterestCorrection`, `WithdrawCorrection`, `NegativeInterestCorrection`, `MarginCorrection`, `FeeCorrection`, `TransferInCorrection`, `TransferOutCorrection`.
# Understanding Your Reports
Tesseract Investment Oy issues two monthly reports to clients of the Earn Direct service: a **Periodic Portfolio Statement** and a **Custody Statement**. Both are provided in electronic format and are available to download and print from the platform.
This page explains what each report contains, what the figures represent, and how key calculations work.
***
### The Two Reports at a Glance
| | Periodic Portfolio Statement | Custody Statement |
| ------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Purpose** | Performance and activity review under the portfolio management mandate (MiCA Article 81) | Confirmation of assets held and transferred under the custody mandate (MiCA Article 75) |
| **Issued by** | Tesseract Investment Oy (portfolio manager) | Tesseract Investment Oy (custodian) |
| **Frequency** | Monthly (minimum quarterly under MiCA) | Monthly (minimum quarterly under MiCA) |
| **Key data** | Holdings, interest earned, deposits/withdrawals, fees | Assets in custody, assets deployed, transfers in and out |
The two reports are complementary. The Portfolio Statement focuses on performance and yield; the Custody Statement focuses on where assets are held and how they moved.
***
## Periodic Portfolio Statement
### Header
Each statement is identified by:
* **Client Name** and **Client ID** — your organisation name and unique identifier on the Tesseract platform
* **Reporting period** — the calendar month covered (e.g. 1.5.2026–31.5.2026)
* **Service provider** — Tesseract Investment Oy
### Portfolio Valuation & Performance
This table is the core of the statement. It shows, for each asset in your portfolio, how much you held at the start and end of the period, what it was worth in euros, and how the value changed.
| Column | What it represents |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **List of assets** | The product and asset (e.g. USDC Lending) |
| **Quantity held (start)** | Number of units held at the opening of the period |
| **Cash value (start)** | Always shown as 0 — Tesseract does not hold or return fiat currency; all assets are received and returned in-kind |
| **Market Value (start)** | Euro value of the opening position, calculated using CoinMarketCap market rates |
| **Quantity held (end)** | Number of units held at the close of the period, after all interest has accrued |
| **Cash value (end)** | Always shown as 0 — same as above |
| **Market Value (end)** | Euro value of the closing position |
| **Change** | Difference in euro market value between start and end |
| **Performance** | Percentage change: (End Market Value − Start Market Value) / Start Market Value |
> **Market value note.** All valuations use the previous day's market rates sourced from CoinMarketCap. Because crypto-asset prices fluctuate, the euro value of your position can change even if no interest has been earned or no transactions have occurred.
**Example — Portfolio Valuation**
Suppose a client holds USDC in the Lending product at a 7% gross annual rate:
| | Start of period (1 May) | End of period (31 May) |
| ------------- | ----------------------- | ---------------------- |
| Quantity held | 100,000.000000 USDC | 100,594.521918 USDC |
| Market value | €94,500.00 | €95,062.82 |
| Change | | +€562.82 |
| Performance | | +0.60% |
The quantity increase of 594.52 USDC represents interest earned over 31 days at 7% per annum (calculated as 100,000 × 7% ÷ 365 × 31 = \~594.52 USDC). The euro value change reflects both the interest accrued and any movement in the USDC/EUR exchange rate.
**A note on performance percentages**
Where a position begins the period at a very small quantity (or near-zero market value), the percentage change can appear extremely large. This is a mathematical consequence of the percentage formula — a move from €0.001 to €5 in market value is technically a very high percentage gain, but reflects a small absolute amount. Always read the **Change** column (absolute euros) alongside the **Performance** column (percentage).
***
### Transactions Summary
This table lists every transaction recorded in your portfolio during the period, one row per event per asset per day.
| Column | What it represents |
| --------------------------- | ---------------------------------------------------------------------- |
| **Date** | Calendar date of the transaction |
| **Type** | Nature of the transaction: `Interest Earned`, `Deposit`, or `Withdraw` |
| **Asset** | The crypto-asset involved |
| **Quantity** | Amount of the asset transacted |
| **Price per unit** | Euro market price of one unit of the asset on that date |
| **Total transaction value** | Quantity × Price per unit, rounded to the nearest euro |
**Transaction types**
`Interest Earned` — recorded daily for every asset in which you have a position. Interest accrues continuously and is credited to your account each day. The quantity credited is small on a daily basis; over a full month it accumulates to the total reflected in the Portfolio Valuation table.
`Deposit` — a transfer of assets into your account by you or on your behalf.
`Withdraw` — a transfer of assets out of your account to your designated wallet.
**Why do daily interest entries show €0 in total transaction value?**
Interest accrues on very small quantities each day. At current market prices, the daily interest on a modest position often rounds to less than €1, so the total transaction value column displays €0. The actual quantity credited (shown in the Quantity column) is precise and accumulates meaningfully over the month.
**Example — Interest calculation for USDC**
A client deposits 100,000 USDC. The applicable gross annual rate is 7%.
| Calculation | Value |
| --------------------- | ----------------------------------------------------- |
| Annual interest | 100,000 × 7% = 7,000 USDC |
| Daily interest | 7,000 ÷ 365 = 19.178082 USDC |
| Day 1 interest entry | 0.019178082 USDC (×1 unit price of €1 = \~€0 rounded) |
| Month total (31 days) | 19.178082 × 31 = 594.52 USDC |
Each day appears as a separate row in the Transactions Summary with the precise daily quantity. The month total is visible in the Portfolio Valuation table as the difference between opening and closing quantity.
**Example — Deposit and withdrawal entries**
On 15 May, a client deposits 5,000 USDC and on 22 May withdraws 2,000 USDC:
| Date | Type | Asset | Quantity | Price per unit | Total value |
| ---------- | -------- | ----- | ---------- | -------------- | ----------- |
| 15/05/2026 | Deposit | USDC | 5,000 USDC | €1 | €5,000 |
| 22/05/2026 | Withdraw | USDC | 2,000 USDC | €1 | €2,000 |
Both entries appear in the Transactions Summary. The net effect (+3,000 USDC) is reflected in the closing quantity in the Portfolio Valuation table, in addition to any interest accrued.
***
### Suitability Assessment Update
This section confirms the date of the most recent suitability assessment conducted by Tesseract Investment Oy under MiCA Article 81, and the basis on which it was last updated (for example, if the client provided new information or Tesseract updated its assessment criteria).
Where no update occurred during the period, the section notes that no new suitability assessment data is available. This does not indicate any issue with the mandate — it simply means the existing assessment remained current for the period.
***
### Costs & Charges
This section provides a full ex-post disclosure of all fees and charges applicable to the reporting period.
| Fee type | Description |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Setup fee** | None — no one-time setup fee is charged |
| **Entry and exit fees** | None — no fees on deposits into or withdrawals from the portfolio |
| **Management fee** | Charged as a percentage of assets under management per annum |
| **Performance fee** | 30% of net profits, subject to a high-water mark; calculated and charged daily in arrears |
| **Transaction fees and costs** | Third-party execution costs deducted directly from the portfolio upon execution; Tesseract does not charge commission on trade execution |
| **Inducements** | Any inducement received by Tesseract in connection with the portfolio management mandate is transferred in full to the client and reported here |
All fees are deducted from the portfolio in crypto-assets, not in fiat currency.
**Performance fee and high-water mark — how it works**
The performance fee is 30% of net profits, calculated daily. The high-water mark means the performance fee is only charged on gains that exceed the portfolio's previous peak value. If the portfolio declines in a period, no performance fee is charged, and the fee only resumes once the portfolio has recovered to its prior peak and continued to grow beyond it.
**Example — Performance fee calculation**
| | Value |
| ------------------------------------ | --------------- |
| Opening portfolio value | 100,000 USDC |
| Closing portfolio value (before fee) | 100,594.52 USDC |
| Net profit | 594.52 USDC |
| Performance fee (30%) | 178.36 USDC |
| Closing portfolio value (after fee) | 100,416.16 USDC |
| New high-water mark | 100,416.16 USDC |
If in the following month the portfolio value falls to 100,200 USDC, no performance fee is charged for that period. The fee only applies again once the portfolio exceeds 100,416.16 USDC.
***
## Custody Statement
### Header
Each statement is identified by:
* **Client Name** and **Client ID** — matching the Portfolio Statement
* **Reporting period** — the calendar month covered
* **Custodian** — Tesseract Investment Oy
### Crypto Assets in Custody
This table shows the state of each asset at the end of the reporting period, from a custody perspective.
| Column | What it represents |
| --------------------- | ------------------------------------------------------------------------------------------ |
| **List of assets** | The product and asset (e.g. USDC Lending) |
| **Amount in custody** | Units held idle in the custody account, not yet deployed |
| **Amount deployed** | Units actively deployed to the lending portfolio on the client's behalf |
| **Total value** | Euro market value of the total position (in custody + deployed), using CoinMarketCap rates |
**Amount in custody vs Amount deployed**
When a client deposits assets, they pass through the custody account before being deployed. Once deployed, the balance moves from *Amount in custody* to *Amount deployed*. In normal operation — where assets are fully deployed — the *Amount in custody* will show 0 and the full balance appears under *Amount deployed*.
**TBC : Negative values in *****Amount deployed***** can appear due to rounding or timing differences between interest accrual and the daily accounting cycle. These are not errors and do not represent a loss of assets.**
**Example — Custody table**
| Asset | Amount in custody | Amount deployed | Total value |
| ------------ | ----------------- | --------------- | --------------- |
| USDC Lending | 0 | 100,416.16 USDC | €95,018.29 |
| ETH Lending | 0 | 2.50000000 ETH | €4,625.00 |
| BTC Lending | 0 | 0.05000000 BTC | €3,301.50 |
| **Total** | | | **€102,944.79** |
All assets have been fully deployed to the lending portfolio. No assets are held idle in custody.
> **Segregation confirmation.** The Custody Statement explicitly confirms that client assets have been legally and operationally segregated from Tesseract's own assets. This confirmation appears in the Additional Information section of every statement.
***
### Activity and Transfers
This table records every movement of assets during the period — into and out of the custody account and between custody and deployment.
| Transaction type | What it means |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| **User deposit** | Assets received from the client's wallet into the Tesseract custody account |
| **Sent to deployment** | Assets moved from the custody account to the lending deployment |
| **Sent to custody** | Assets returned from deployment back to the custody account (e.g. ahead of a withdrawal) |
| **Withdraw to user** | Assets sent from the custody account back to the client's wallet |
**Example — Deposit flow**
A client deposits 5,000 USDC on 15 May. The custody statement shows:
| Date | Type | Asset | Quantity | Value |
| ---------- | ------------------ | ----- | ---------- | ------ |
| 15/05/2026 | User deposit | USDC | 5,000 USDC | €4,725 |
| 15/05/2026 | Sent to deployment | USDC | 5,000 USDC | €4,725 |
The deposit is received into custody and immediately deployed. Both entries are recorded, giving a complete chain of custody for the assets.
**Example — Withdrawal flow**
A client withdraws 2,000 USDC on 22 May. The custody statement shows:
| Date | Type | Asset | Quantity | Value |
| ---------- | ---------------- | ----- | ---------- | ------ |
| 22/05/2026 | Sent to custody | USDC | 2,000 USDC | €1,892 |
| 22/05/2026 | Withdraw to user | USDC | 2,000 USDC | €1,892 |
Assets are recalled from deployment into custody, then transferred to the client's wallet. The sequence confirms full traceability from deployment to the client's address.
***
### How the Two Reports Relate
The Portfolio Statement and Custody Statement cover the same period and the same client, but from different perspectives.
| | Portfolio Statement | Custody Statement |
| ----------------------------------- | ------------------------- | ----------------------------------------------------------- |
| Shows interest earned | ✓ (Transactions Summary) | ✗ |
| Shows euro performance | ✓ (Portfolio Valuation) | ✗ |
| Shows fees charged | ✓ (Costs & Charges) | ✗ |
| Shows assets in custody vs deployed | ✗ | ✓ |
| Shows deposit/withdrawal flows | ✓ (as Deposit / Withdraw) | ✓ (as User deposit / Withdraw to user + internal transfers) |
| Confirms asset segregation | ✗ | ✓ (Additional Information) |
A deposit of 5,000 USDC on 15 May appears in the Portfolio Statement as a single `Deposit` entry, and in the Custody Statement as two entries (`User deposit` followed by `Sent to deployment`). Both records refer to the same event — the Custody Statement simply provides greater granularity on the internal movement of assets.
***
> **Risks.** Discretionary portfolio management of crypto-assets involves significant risks, including smart contract risk, DeFi protocol risk, oracle risk, liquidity risk, market stress risk, counterparty risk, custody risk and regulatory change risk, and the risk of total loss of capital. Yields are indicative only, not guaranteed, and will vary.
***
*This website is a marketing communication of Tesseract Investment Oy, a crypto-asset service provider authorised under Regulation (EU) 2023/1114 (MiCA) by the Finnish Financial Supervisory Authority (FIN-FSA). It is directed at institutional counterparties under a non-disclosure agreement with Tesseract. It is not an offer or solicitation.*
# FAQ
Frequently asked questions about Earn API and Earn Direct. For DCV-specific questions, see [Dedicated Client Vaults → FAQ](/dedicated-client-vaults/faq).
### General
**How does the Earn API platform work?**
The platform enables partners to establish cryptocurrency accounts, deposit funds, and generate interest earnings. Many partners leverage this service on behalf of their own customer base.
**How do I connect to the API?**
Partners require API credentials (Client ID and Client Secret) to obtain bearer tokens. Detailed connection instructions are available at the [API documentation portal](https://earn-api.partner.env.tesseractinvestment.dev/docs/).
**How do I create a deposit or withdrawal?**
Account creation precedes any deposit activity, organized by product type and user. Once established, the deposit and withdrawal endpoints manage capital transfers. Actual asset movements occur daily; these operations function as accounting transactions. Withdrawals require positive account balances, with actual transfers completing at cycle end.
**How do I settle the outstanding balance with Tesseract?**
Deposits and withdrawals net against each other. Negative balances require partner asset transfers to Tesseract; positive balances receive automatic or manual transfers based on approval thresholds. See [Settlements](/earn-direct-and-earn-api/earn-api/settlements).
**How do I get reports out of the system?**
Daily reports generate at accounting-cycle completion. See [Working with Reports](/earn-direct-and-earn-api/working-with-reports).
**Are there any fixed fees for using the platform?**
No — there are no fixed costs or partner transaction fees.
**How does Tesseract make money?**
When Tesseract gives you the rates, its share has already been discounted from the fixed interest rate.
**Who pays the network fees?**
The party initiating the transfer bears the network costs.
**How do you handle decimals?**
All currencies use 18-decimal precision throughout the system, supporting values down to `1e-18`. Interest below this threshold is rounded, with zero results not distributed.
### Partner questions
**If we don't have any users, how do we integrate?**
Create a company-representative user with per-currency accounts for capital deployment.
**Why don't we as a partner have an account?**
User accounts must exist before company accounts can function.
**Are you staking our assets?**
Staking occurs upon mutual agreement.
**Why don't our users just send you the Bitcoin?**
The platform is built as a B2B(2C) platform. To simplify operations and save gas fees, end users don't send assets on their own — settlement happens between partner and Tesseract.
**How do we withdraw the interest we earn as a partner?**
Daily settlement typically applies. Partners without users may create per-currency accounts with matching interest rates to access interest via withdrawals.
**Can we settle or transfer our partner margin on a non-daily basis, separate from user transactions?**
No — the system prioritizes cost-efficiency while providing comprehensive settlement data.
**Can Tesseract suspend, ban, or delete users?**
Partners retain this authority.
**Are products fixed? Is it safe to save products for future calls?**
Yes — product IDs remain constant within each environment.
**Is `/users/{userId}/account` available in production?**
No — partners should maintain transaction records internally and reconcile daily reports containing system-generated interest transactions.
**What is the `*Correction` transaction type?**
A correction transaction is a transaction that negates a previous transaction.
**Is account balance affected immediately after deposit or withdrawal calls?**
Yes — however, user-facing balances should derive from partner systems.
**What does the usual settlement flow look like?**
Use the `/outstanding-balance` endpoint for settlement verification.
**When do blockchain transfers to partners occur?**
Transfers from Tesseract's system are automatically initiated during the daily accounting cycle.
**When should partners initiate blockchain transfers?**
Within 24 hours following daily accounting completion.
**If settlement occurs after midnight, do users wait longer to earn interest?**
Users begin earning immediately upon successful deposit. Interest accrual on withdrawals excludes the final day.
**Is the outstanding balance updated only daily?**
Yes — however, interest accrual begins immediately upon successful API deposit.
**Can accounting use UTC instead of +2 timezone?**
Timezone configuration accommodates partner preferences.