Deploy to Ekubo

This is the end-to-end guide for deploying liquidity into Ekubo from the zkde.fi app. Ekubo is the primary DEX integration — swap, LP add, fee collection, and position management all route through the Ekubo adapter.

Entry point

Open /agent?v=vault&sub=deploy in Capital OS. This is the deployment surface within the Vault.

The flow

sequenceDiagram
  participant You
  participant UI as Vault Deploy UI
  participant API as Orchestration API
  participant Wallet
  participant Chain as Starknet

  You->>UI: Set amount + risk profile
  UI->>API: POST /orchestration/deploy
  API-->>UI: deployment payload + receipt_id
  You->>Wallet: Sign execution tx
  Wallet->>Chain: Submit tx
  You->>UI: Click "Confirm"
  UI->>API: POST /orchestration/receipt/confirm
  API-->>UI: confirmed ✓ with tx_hash

Walking through it:

1. Configure — enter the amount you want to deploy and your risk profile context. This isn't just a number — the system uses your risk profile to determine pool selection and allocation strategy.

2. Request payload — the UI calls the orchestration API, which builds a deployment payload. This includes the specific Ekubo pool(s), token approvals needed, calldata for the LP operation, and a receipt ID for tracking.

3. Sign — your wallet prompts for signatures. Depending on the operation, this might be one tx (simple swap) or multiple (approve + add liq).

4. Confirm — after the tx lands on-chain, you confirm back through the UI. The API attaches your tx hash to the receipt, closing the loop.

5. Monitor — your position shows up in Vault's portfolio view. Yield accrual, position health, and rebalance triggers are tracked from here.

Endpoints

Method	Path	What it does
POST	/api/v1/zkdefi/orchestration/deploy	Build deployment payload — pool selection, calldata, receipt ID
GET	/api/v1/zkdefi/orchestration/receipt/{receipt_id}	Check receipt state — pending, confirmed, failed
POST	/api/v1/zkdefi/orchestration/receipt/confirm	Attach tx hash to receipt, mark as confirmed

What can go wrong

Situation	What's happening	What to do
Ekubo API unavailable	Downstream Ekubo service is down. Your tx may have succeeded on-chain but the UI doesn't know yet.	Check your tx hash on Voyager. Wait for indexer sync — the UI will catch up.
Network mismatch	Your wallet is connected to the wrong network. Contract address resolution fails silently.	Switch to Starknet Sepolia in your wallet settings before retrying.
Insufficient balance	The orchestration payload built fine (it's just math), but your wallet can't fund the actual tx — not enough gas or tokens.	Check both ETH (for gas) and the token you're deploying. The payload calculation doesn't verify your balance.
Stuck on "pending"	Receipt was created but never confirmed. Usually means the tx was never submitted or submission failed.	Check if the tx hash exists on-chain. If not, re-request the payload and try again.