Deposit into a vault

A deposit moves assets from a user’s wallet into your organization’s fee wrapper for a vault. The token approval and the vault deposit execute as a single atomic batch transaction, so there is no separate approval step to manage.

Earn is in private beta. Contact us to enable it for your organization.

Prerequisites

Your organization has deployed a wrapper for the vault, and its deployment status is COMPLETED. Deposits targeting an address with no deployed wrapper fail with EARN_SETUP_REQUIRED.
The signWith wallet holds enough of the vault’s underlying asset. For non-sponsored deposits it also needs the chain’s native token for gas.

Sub-organization wallets can deposit into (and withdraw from) wrappers deployed by their parent organization. The wrapper configuration lives on the parent, the sub-org wallet signs, and no per-sub-org deployment is needed.

Submit the deposit

enum<string>

required

ACTIVITY_TYPE_EARN_DEPOSIT

string

required

Timestamp (in milliseconds) of the request, used to verify liveness.

string

required

Unique identifier for your organization (or the sub-organization whose wallet is depositing).

string

required

Address of the deployed fee wrapper to deposit into, from earn_enabled_vaults.

string

required

The wallet account address to deposit from and sign with.

string

required

Amount of the underlying asset to deposit, in raw on-chain units (e.g. "1000000" for 1 USDC at 6 decimals).

string

required

CAIP-2 chain identifier, e.g. eip155:8453.

Whether to sponsor the transaction’s gas via Gas Station. Defaults to false.

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/earn_deposit \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <string> (see Stamps)" \
  --data '{
    "type": "ACTIVITY_TYPE_EARN_DEPOSIT",
    "timestampMs": "<string> (e.g. 1745474677453)",
    "organizationId": "<ORGANIZATION_ID>",
    "parameters": {
      "wrapperAddress": "<WRAPPER_ADDRESS>",
      "signWith": "<WALLET_ADDRESS>",
      "assets": "1000000",
      "chainCaip2": "eip155:8453",
      "sponsor": false
    }
  }'

import { TurnkeyClient } from "@turnkey/http";
import { ApiKeyStamper } from "@turnkey/api-key-stamper";

const client = new TurnkeyClient(
  { baseUrl: "https://api.turnkey.com" },
  new ApiKeyStamper({
    apiPublicKey: process.env.TURNKEY_API_PUBLIC_KEY,
    apiPrivateKey: process.env.TURNKEY_API_PRIVATE_KEY,
  }),
);

const { activity } = await client.request("/public/v1/submit/earn_deposit", {
  type: "ACTIVITY_TYPE_EARN_DEPOSIT",
  timestampMs: String(Date.now()),
  organizationId: "<ORGANIZATION_ID>",
  parameters: {
    wrapperAddress: "<WRAPPER_ADDRESS>",
    signWith: "<WALLET_ADDRESS>",
    assets: "1000000",
    chainCaip2: "eip155:8453",
    sponsor: false,
  },
});

The result contains only a poll handle:

{
  "activity": {
    "id": "<ACTIVITY_ID>",
    "status": "ACTIVITY_STATUS_COMPLETED",
    "type": "ACTIVITY_TYPE_EARN_DEPOSIT",
    "result": {
      "earnDepositResult": {
        "depositRequestId": "<DEPOSIT_REQUEST_ID>"
      }
    }
  }
}

Gas: sponsored vs self-funded

With sponsor: true, Gas Station pays the gas and the batch executes as an EIP-7702 sponsored transaction. The signWith wallet needs no native token at all. This requires a Pro plan or higher. With sponsor: false, the signWith wallet pays gas itself, so fund it with the chain’s native token before depositing.

Poll deposit status (required)

A COMPLETED activity means the transaction was enqueued for broadcast, not that it landed on-chain. A transaction that later fails (for example, from an insufficient token balance) is invisible in the activity result. Poll earn_deposit_status until it reports COMPLETED (included on-chain) or FAILED.

curl --request POST \
  --url https://api.turnkey.com/public/v1/query/earn_deposit_status \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <string> (see Stamps)" \
  --data '{
    "organizationId": "<ORGANIZATION_ID>",
    "depositRequestId": "<DEPOSIT_REQUEST_ID>"
  }'

const status = await client.request("/public/v1/query/earn_deposit_status", {
  organizationId: "<ORGANIZATION_ID>",
  depositRequestId: "<DEPOSIT_REQUEST_ID>",
});

{
  "status": "COMPLETED",
  "depositTxHash": "<TRANSACTION_HASH>"
}

status is PENDING, COMPLETED, or FAILED. On FAILED, the response includes an error field with the reason. See Submissions for general activity semantics.

Next steps

Track positions once the deposit is COMPLETED
Withdraw from a vault

Get started

Features

Reference

Deposit into a vault

Prerequisites

Submit the deposit

Gas: sponsored vs self-funded

Poll deposit status (required)

Next steps

​Prerequisites

​Submit the deposit

​Gas: sponsored vs self-funded

​Poll deposit status (required)

​Next steps

Prerequisites

Submit the deposit

Gas: sponsored vs self-funded

Poll deposit status (required)

Next steps