Deposit

Initiates a deposit of assets into a portfolio's vault. This endpoint automatically creates vaults if they don't exist and generates the necessary transaction payload for sending assets from an external wallet.

Request URL

POST https://ddp.definitive.fi/v2/organization/portfolios/{portfolioId}/deposit

Path Parameters

Parameter	Type	Required	Description
portfolioId	string	Yes	UUID of the portfolio

Request Body

Field	Type	Required	Description
chain	string	Yes	Blockchain network (`"solana"`, `"ethereum"`, `"polygon"`, `"arbitrum"`, `"base"`)
asset	string	Yes	Asset contract/mint address. For native tokens: use `"11111111111111111111111111111111"` (Solana) or `"0x0000000000000000000000000000000000000000"` (EVM chains)
amount	string	Yes	Amount to deposit (in human-readable format, e.g., `"1.5"` for 1.5 ETH)
walletAddress	string	No	User wallet address sending the funds (required for Solana)
sponsorAddress	string	No	Optional fee sponsor (Solana only)
address	string	Yes	Address to associate with vault creation (required for EVM chains)

Examples

Solana Deposit

const solanaDeposit = await AuthHelpers.signAndSend({
  path: "/v2/organization/portfolios/00000000-0000-0000-0000-000000000001/deposit",
  method: "POST",
  body: {
    chain: "solana",
    asset: "So11111111111111111111111111111111111111112", // Wrapped SOL
    amount: "0.01", // 0.01 SOL
    walletAddress: "GszaaaaaaaaaaaaaaaaaaaaaaaaVcx",
    sponsorAddress: "optional sponsor pubkey",
    address: "optional address",
  },
  organizationId: "00000000-0000-0000-0000-000000000000",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

EVM Deposit (Native Token)

const ethDeposit = await AuthHelpers.signAndSend({
  path: "/v2/organization/portfolios/00000000-0000-0000-0000-000000000001/deposit",
  method: "POST",
  body: {
    chain: "ethereum",
    asset: "0x0000000000000000000000000000000000000000", // Native ETH
    amount: "1.0", // 1 ETH
    walletAddress: "0x742d35Cc6634C0532925a3b8D400eE6a0b8CBd6",
    address: "0x742d35Cc6634C0532925a3b8D400eE6a0b8CBd6",
  },
  organizationId: "00000000-0000-0000-0000-000000000000",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

EVM Deposit (ERC-20 Token)

const usdcDeposit = await AuthHelpers.signAndSend({
  path: "/v2/organization/portfolios/00000000-0000-0000-0000-000000000001/deposit",
  method: "POST",
  body: {
    chain: "ethereum",
    asset: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
    amount: "100.0", // 100 USDC
    walletAddress: "0x742d35Cc6634C0532925a3b8D400eE6a0b8CBd6",
    address: "0x742d35Cc6634C0532925a3b8D400eE6a0b8CBd6",
  },
  organizationId: "00000000-0000-0000-0000-000000000000",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

Response Formats

Solana Response

{
  transaction: "base64-encoded transaction string",
  transactionFee: "0.000005"
}

EVM Response

{
  payload: {
    to: "0x92b9689B61bA47bD5B558FC358591C65a8305886", // Contract address to call
    data: "0x", // Call data (empty for native token transfers)
    value: "1000000000000000000" // Wei amount (for native tokens)
  },
  vaultAddress: "0x1234567890abcdef1234567890abcdef12345678" // The vault address where funds will be deposited
}

Response Fields

EVM Response Fields

Field	Type	Description
payload.to	string	Contract address to call (vault address for native tokens, token contract for ERC-20)
payload.data	string	Call data (empty for native tokens, encoded transfer function for ERC-20)
payload.value	string	Wei amount to send (for native tokens only)
vaultAddress	string	The vault address where funds will be deposited

Solana Response Fields

Field	Type	Description
transaction	string	Base64-encoded transaction to sign and submit
transactionFee	string	Estimated transaction fee in SOL

Usage Notes

Solana

✨ Now with automatic rent sponsorship! No upfront 0.0138 SOL required
Both wrapped SOL (So11111111111111111111111111111111111111112) and native SOL (11111111111111111111111111111111) are supported
Native SOL addresses automatically map to wrapped SOL for deposit processing
Enhanced error messages provide clear guidance for common issues
The response contains a base64-encoded transaction that users sign and submit
Deposits are automatically credited to the vault upon confirmation
Definitive sponsors rent: Users only need minimal SOL for transaction fees (~0.000005 SOL)

EVM Chains

Native tokens (ETH, MATIC, etc.) use "0x0000000000000000000000000000000000000000" as the asset address
ERC-20 tokens use their contract address
For native token deposits: data will be "0x" and value contains the wei amount
For ERC-20 deposits: data contains the encoded transfer() call and value is "0"
Users execute the returned transaction payload to complete the deposit
Vaults are created automatically if they don't exist for the portfolio and chain
The address parameter is required and specifies which address should be associated with vault creation
The vaultAddress in the response indicates where funds will be deposited and can be used for tracking or verification

Error Handling

Common error responses:

Error Code	Description
`INVALID_ASSET`	Asset not supported on the specified chain
`INVALID_AMOUNT`	Amount is invalid or below minimum
`VAULT_CREATION_FAILED`	Failed to create vault for the specified chain and portfolio

Common Pitfalls & Tips

⚠️ portfolioId is required: Always use the correct portfolio UUID in the path. The backend uses this to route and authorize your request.
⚠️ EVM deposits require the address field: For EVM chains, the address field is mandatory and should match the wallet that will send the deposit transaction. If missing or incorrect, vault creation or deposit will fail.
⚠️ SVM deposits require the walletAddress field: For Solana, always provide the user's wallet address.
Vaults are auto-created: If a vault does not exist for the portfolio and chain, it will be created automatically during deposit.
Authentication: Requests must be signed and include the correct headers. See Request Authorization for details on required headers and signature generation.
Native tokens: For EVM, use 0x0000000000000000000000000000000000000000 as the asset address for native tokens (ETH, MATIC, etc.).
Test with small amounts first: To avoid failed transactions due to misconfiguration, always test with small amounts before production use.

Solana Deposit Flow

The existing /deposit endpoint now includes automatic rent sponsorship for Solana deposits! This eliminates common issues where users couldn't deposit because they lacked the ~0.0138 SOL required for vault rent.

Automatic Solana Improvements (New!)

When using the standard deposit endpoint with Solana, you automatically get:

✅ No Rent Required: Definitive sponsors the Solana rent cost (~0.0138 SOL)
✅ Proper Solana Support: Native SOL address (11111111111111111111111111111111) and backwards compatibility with EVM-style addressing
✅ Improved Error Messages: Clear, actionable error messages for Solana-specific issues
✅ Optimized Flow: Uses a two-step process that avoids premature vault creation

Enhanced Solana Examples

Native SOL

const nativeSolDeposit = await AuthHelpers.signAndSend({
  path: "/v2/organization/portfolios/00000000-0000-0000-0000-000000000001/deposit",
  method: "POST",
  body: {
    chain: "solana",
    asset: "11111111111111111111111111111111", // Native SOL (System Program)
    amount: "0.01", // 0.01 SOL - no rent required!
    walletAddress: "GszaaaaaaaaaaaaaaaaaaaaaaaaVcx",
    address: "GszaaaaaaaaaaaaaaaaaaaaaaaaVcx",
  },
  organizationId: "00000000-0000-0000-0000-000000000000",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

Wrapped SOL (Direct)

const wrappedSolDeposit = await AuthHelpers.signAndSend({
  path: "/v2/organization/portfolios/00000000-0000-0000-0000-000000000001/deposit",
  method: "POST",
  body: {
    chain: "solana",
    asset: "So11111111111111111111111111111111111111112", // Wrapped SOL
    amount: "0.01", // 0.01 SOL - rent sponsored!
    walletAddress: "GszaaaaaaaaaaaaaaaaaaaaaaaaVcx",
    address: "GszaaaaaaaaaaaaaaaaaaaaaaaaVcx",
  },
  organizationId: "00000000-0000-0000-0000-000000000000",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

SPL Token (e.g., BONK)

const bonkDeposit = await AuthHelpers.signAndSend({
  path: "/v2/organization/portfolios/00000000-0000-0000-0000-000000000001/deposit",
  method: "POST",
  body: {
    chain: "solana",
    asset: "2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv", // BONK token
    amount: "1000", // 1000 BONK - rent sponsored!
    walletAddress: "GszaaaaaaaaaaaaaaaaaaaaaaaaVcx",
    address: "GszaaaaaaaaaaaaaaaaaaaaaaaaVcx",
  },
  organizationId: "00000000-0000-0000-0000-000000000000",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

What's New for Solana

Feature	Before	After
Rent Cost	User pays ~0.0138 SOL upfront	✅ Definitive sponsors rent
Asset Address	Only wrapped SOL address accepted	✅ Native SOL `11111111...` + backwards compatibility
Error Messages	Generic "invalid mint" errors	✅ Clear, actionable error messages
Flow	Single-step with premature vault creation	✅ Optimized two-step flow