Deposits & withdrawals

9. Authentication

All deposit and withdrawal operations go through the DiversiFi API. You will need an API key to interact with these endpoints.

Contact the DiversiFi team to obtain an API key. Keys are prefixed with dfi_ and must be sent as a Bearer token on every request:

Authorization: Bearer dfi_your_api_key_here

Rate limit: 120 requests per minute per API key.

Required permission scope: position_management (for deposits, withdrawals, and refunds). Read-only endpoints require only read_only.

---

10. Deposit Flow

Depositing USDC into a basket is a two-step process:

1. Get an unsigned transaction from the API — the server builds and returns a base64-encoded Solana transaction.

2. Sign and submit it with the user's wallet, then confirm it with the API.

Step 1 — Get the unsigned deposit transaction

GET /v1/positions/open/tx

Parameter	Type	Required	Description
basket_address	string	Yes	The basket address / Index PDA (base58)
amount	number	Yes	USDC amount to deposit (human-readable, e.g. 100.5)

Response:

{
  "success": true,
  "data": {
    "unsignedTxs": ["<base64-encoded transaction>"]
  }
}

unsignedTxs is an array. Sign and submit each transaction in order.

Error responses:

message	Cause
"Basket not found"	Invalid basket_address
"Minimum deposit for <BasketName> is X USDC."	Amount below the per-basket minimum
"Basket operations are currently paused"	Basket temporarily disabled

Step 2 — Sign, submit, and confirm

After signing and submitting the transaction to the Solana network, pass the resulting signature back to the API:

GET /v1/positions/open/confirm

Parameter	Type	Required	Description
basket_address	string	Yes	Same basket address used in step 1
signature	string	Yes	The Solana transaction signature

Response:

{
  "success": true,
  "message": "Transaction executed.",
  "data": { "executedAt": "2025-03-24T12:34:56.789Z" }
}

Once confirmed, the DiversiFi backend automatically executes the Jupiter swaps and mints LP tokens to the user's wallet.

---

11. Withdrawal Flow

Withdrawing converts LP tokens back to USDC. Same two-step pattern as deposits.

Step 1 — Get the unsigned withdrawal transaction

GET /v1/positions/close/tx

Parameter	Type	Required	Description
basket_address	string	Yes	The basket address / Index PDA (base58)
amount	number	Yes	LP token amount to withdraw (human-readable)

Response: Same shape as the deposit response — unsignedTxs array.

Step 2 — Sign, submit, and confirm

GET /v1/positions/close/confirm

Parameter	Type	Required	Description
basket_address	string	Yes
signature	string	Yes	The Solana transaction signature

After confirmation, the backend swaps each constituent token back to USDC. Fees are deducted at this stage. USDC lands in the user's wallet automatically.

---

12. Cancelling Pending Operations

If a deposit or withdrawal is stuck, users can cancel and reclaim their locked tokens.

Check refund eligibility

GET /v1/positions/refund/check

Parameter	Type	Required
basket_address	string	Yes

Response:

{
  "success": true,
  "data": {
    "canRefund": true,
    "refundType": "deposit",
    "deposit": { "hasPending": true, "hasBalance": true, "balance": 100.5, "canRefund": true },
    "withdrawal": { "hasPending": false, "hasBalance": false, "balance": 0, "canRefund": false }
  }
}

refundType is "deposit", "withdrawal", or null.

Note: refund/check returns "withdrawal" (with -al) but refund/tx accepts "withdraw" (without). Normalize before passing: refundType === "withdrawal" ? "withdraw" : refundType.

Get the unsigned refund transaction

GET /v1/positions/refund/tx

Parameter	Type	Required	Description
basket_address	string	Yes
refund_type	string	Yes	"deposit" or "withdraw"

Response:

{
  "success": true,
  "data": {
    "unsignedTx": "<base64-encoded transaction>",
    "transactionType": "deposit"
  }
}

Sign, submit, and confirm the refund

GET /v1/positions/refund/confirm

Parameter	Type	Required	Description
basket_address	string	Yes
refund_signature	string	Yes	The refund transaction signature

Only the unprocessed portion of a deposit/withdrawal is refunded. If the backend partially executed swaps before the cancel, those cannot be reversed.

---

13. Reading Positions and History

These endpoints require only read_only permission.

User positions

GET /v1/positions/

Returns all open and closed positions for the authenticated wallet, including current value, ROI, PnL, and refund eligibility.

Portfolio summary

GET /v1/portfolio

Returns an aggregate summary across all positions: total invested, total current value, total ROI.

Transaction history

GET /v1/positions/transactions

Parameter	Type	Required	Description
basket_id	string	No	Filter by basket
limit	number	No	Max results (default 50, max 200)

Each transaction includes its type (Deposit, Withdrawal, Refund), status (completed, processing, partially_completed, failed, refunded, pending), amounts, timestamps, and the individual swap signatures.

---

14. Example TypeScript Implementation

See deposit_withdraw_example.ts for a complete working example of the deposit and withdrawal flows using the API.