Example: Neobank/Exchanges

Set autoRebalance: false when creating the wallet so your application controls exact dollar allocations and deposits remain in cash until you allocate them. Store your API key in GROUND_API_TOKEN. The examples below use the sandbox API:

const baseUrl = "https://sandbox.groundtech.co";
const apiToken = process.env.GROUND_API_TOKEN!;

1. Create a wallet for each customer

Create a wallet without auto-rebalancing by setting autoRebalance: false. Save the Ground wallet ID on your customer record.

type Wallet = {
  id: string;
  autoRebalance: boolean;
  status: string;
  depositAddresses: Record<string, string>;
  positions: Array<{
    id: string;
    kind: string;
    label: string;
    valueUsd: string;
  }>;
};

async function createCustomerWallet(customerId: string) {
  const response = await fetch(`${baseUrl}/v2/wallets`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      requestId: crypto.randomUUID(),
      label: `Customer ${customerId}`,
      autoRebalance: false,
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  const wallet = (await response.json()) as Wallet;

  await saveGroundWalletId(customerId, wallet.id);
  return wallet;
}

const customerWallet = await createCustomerWallet("customer-1234");

Subscribe to portfolio_wallet.status_changed before creating the wallet. When the matching walletId reaches idle, read GET /v2/wallets/{id} and show the customer the appropriate deposit address. Handle failed as a provisioning failure, and use the wallet read to reconcile a delayed or missed webhook.

2. Receive the completed deposit

Subscribe to portfolio_wallet.deposit.status_changed or poll the wallet’s deposits. Allocate funds only after the deposit becomes completed. Verify the webhook signature before parsing it, and deduplicate deliveries with the Ground-Event-Id header.

type CompletedDeposit = {
  id: string;
  walletId: string;
  amount: string;
  status: "completed";
  cashPositionId: string;
};

type DepositWebhook = {
  event: "portfolio_wallet.deposit.status_changed";
  deposit: {
    id: string;
    walletId: string;
    amount: string;
    status: "processing" | "completed" | "failed";
    cashPositionId: string | null;
  };
};

async function handleDepositEvent(event: DepositWebhook) {
  if (event.deposit.status !== "completed") return;
  if (!event.deposit.cashPositionId) return;

  await allocateDeposit(
    event.deposit as CompletedDeposit,
    "morpho-august-usdc-v2",
  );
}

Use cashPositionId as the source when allocating this deposit. IDs are unique to each environment, so do not reuse sandbox IDs in production. See Webhook signature verification for the complete verification flow. Use the wallet read as a fallback when a webhook is delayed or missed.

3. Allocate the cash

Fetch GET /v2/wallets/yield-sources and use a returned source id as the destination. Send the same allocations array to preview and create.

async function allocateDeposit(
  deposit: CompletedDeposit,
  yieldSourceId: string,
) {
  const allocations = [
    {
      from: deposit.cashPositionId,
      to: yieldSourceId,
      amountUsd: deposit.amount,
    },
  ];

  const previewResponse = await fetch(
    `${baseUrl}/v2/wallets/${deposit.walletId}/allocate-preview`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiToken}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ allocations }),
    },
  );
  if (!previewResponse.ok) throw new Error(await previewResponse.text());
  const preview = await previewResponse.json();

  const allocationResponse = await fetch(
    `${baseUrl}/v2/wallets/${deposit.walletId}/allocate`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiToken}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        requestId: crypto.randomUUID(),
        allocations,
      }),
    },
  );
  if (!allocationResponse.ok) throw new Error(await allocationResponse.text());
  const allocation = await allocationResponse.json();

  return { preview, allocation };
}

The response includes the rebalanceId, requestId, createdAt, current status, and accepted allocations. Returned dollar amounts use six decimal places. Track portfolio_wallet.rebalance.status_changed or rebalance activity until it finishes. If Ground returns workflow_conflict, wait for the active withdrawal or rebalance to finish, then retry.

4. Read or change an allocation

Read the wallet to get the customer’s current cash and investments:

const response = await fetch(`${baseUrl}/v2/wallets/${customerWallet.id}`, {
  headers: { Authorization: `Bearer ${apiToken}` },
});

if (!response.ok) throw new Error(await response.text());
const wallet = (await response.json()) as Wallet;
console.log(wallet.positions);

To move an existing investment, use IDs from wallet.positions:

const allocations = [
  {
    from: "morpho-august-usdc-v2",
    to: "syrup-usdc",
    amountUsd: "250.000000",
  },
];

const previewResponse = await fetch(
  `${baseUrl}/v2/wallets/${customerWallet.id}/allocate-preview`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ allocations }),
  },
);

if (!previewResponse.ok) throw new Error(await previewResponse.text());

const allocationResponse = await fetch(
  `${baseUrl}/v2/wallets/${customerWallet.id}/allocate`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      requestId: crypto.randomUUID(),
      allocations,
    }),
  },
);

if (!allocationResponse.ok) {
  throw new Error(await allocationResponse.text());
}

5. View yield

Read the customer’s lifetime earnings, estimated annualized yield, and current breakdown by yield source:

type WalletYield = {
  walletId: string;
  earnedUsd: string;
  annualizedUsd: string;
  currentBalanceUsd: string;
  positions: Array<{
    yieldSourceId: string;
    name: string;
    apyBps: number | null;
    deployedValueUsd: string;
  }>;
};

const response = await fetch(
  `${baseUrl}/v2/wallets/${customerWallet.id}/yield`,
  { headers: { Authorization: `Bearer ${apiToken}` } },
);

if (!response.ok) throw new Error(await response.text());
const customerYield = (await response.json()) as WalletYield;

console.log({
  earnedUsd: customerYield.earnedUsd,
  annualizedUsd: customerYield.annualizedUsd,
  positions: customerYield.positions,
});

This response can be shown directly in the customer-facing application. See Calculating Yield Accrual for display and calculation guidance.

6. Withdraw funds

Omit sources to let Ground choose the positions. To withdraw from specific positions, include the amount from each source. Source amounts must add up to amountUsd, and each source must contribute at least $0.01.

const withdrawalRequest = {
  amountUsd: 1_000,
  token: "usdc",
  destinationChain: "ethereum_sepolia",
  sources: [
    { id: "morpho-august-usdc-v2", amountUsd: 600 },
    { id: "syrup-usdc", amountUsd: 400 },
  ],
};

const previewResponse = await fetch(
  `${baseUrl}/v2/wallets/${customerWallet.id}/withdrawal-preview`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(withdrawalRequest),
  },
);

if (!previewResponse.ok) throw new Error(await previewResponse.text());
const preview = await previewResponse.json();

const withdrawalResponse = await fetch(
  `${baseUrl}/v2/wallets/${customerWallet.id}/withdrawals`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ...withdrawalRequest,
      requestId: crypto.randomUUID(),
      destinationAddress: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    }),
  },
);

if (!withdrawalResponse.ok) throw new Error(await withdrawalResponse.text());
const withdrawal = await withdrawalResponse.json();

console.log({ preview, withdrawal });

Send the same source amounts to preview and create. Track portfolio_wallet.withdrawal.status_changed until the withdrawal finishes.

Test the integration

In sandbox:

Create a wallet without automatic rebalancing and save its ID on a test customer.
Deposit test USDC and confirm the completed deposit includes cashPositionId.
Allocate part of the cash to two yield sources.
Confirm the rebalance finishes and the wallet returns the new positions.
Confirm GET /v2/wallets/{id}/yield returns the customer’s yield summary.
Move funds between two existing positions.
Complete one automatic withdrawal and one selected-source withdrawal.

Save each requestId before sending a request. If the request times out, retry with the same ID and body.

Getting Started

Wallet Lifecycle

Approvals

Monitoring & Webhooks

Security

Resources

Example: Neobank/Exchanges

1. Create a wallet for each customer

2. Receive the completed deposit

3. Allocate the cash

4. Read or change an allocation

5. View yield

6. Withdraw funds

Test the integration

​1. Create a wallet for each customer

​2. Receive the completed deposit

​3. Allocate the cash

​4. Read or change an allocation

​5. View yield

​6. Withdraw funds

​Test the integration

1. Create a wallet for each customer

2. Receive the completed deposit

3. Allocate the cash

4. Read or change an allocation

5. View yield

6. Withdraw funds

Test the integration