Integration details

These rules apply to every Earn integration. Read them before you take real deposits.

Slippage floorsCopy Anchor Link

A floor is the least a transaction may return: minSharesOut on a deposit, minAmountOut on a withdrawal. A strategy's depositSlippage and withdrawalSlippage say whether it takes one, as Read the slippage policy shows. When a policy is not null, preview first and send the floor: the build refuses the transaction without it.

A null policy means the transaction cannot enforce a floor: a provider order is priced later, and some sandbox vaults lack the floor instruction. Omit the floor then, because a build refuses one it cannot enforce. In production, nearly every deposit takes a floor. A preview quotes the rate; it does not reserve it.

Compute the floor in integer base units, never with a JavaScript number:

/** Takes `toleranceBps` off a decimal quote, rounding down to the mint's scale. */
export function floorForTolerance(quote: string, decimals: number, toleranceBps: number): string {
  if (!Number.isInteger(toleranceBps) || toleranceBps < 1 || toleranceBps > 1_000) {
    throw new Error("Tolerance must be 1 to 1,000 basis points");
  }
  const [whole = "", fraction = ""] = quote.split(".");
  const significant = fraction.replace(/0+$/, "");
  if (!/^\d+$/.test(whole) || !/^\d*$/.test(fraction) || significant.length > decimals) {
    throw new Error("The quote is not a decimal at the mint's scale");
  }
  const units = BigInt(whole + significant.padEnd(decimals, "0"));
  if (units === 0n) throw new Error("The quote is zero");
  const floored = (units * BigInt(10_000 - toleranceBps)) / 10_000n || 1n;
  const digits = floored.toString().padStart(decimals + 1, "0");
  if (decimals === 0) return digits;
  const fractionPart = digits.slice(-decimals).replace(/0+$/, "");
  return fractionPart ? `${digits.slice(0, -decimals)}.${fractionPart}` : digits.slice(0, -decimals);
}

// floorForTolerance("50", 6, 10) returns "49.95": a 10 bps floor on 50 shares.

Use the preview's shareDecimals for a deposit floor and assetDecimals for a withdrawal floor. Start from the policy's defaultToleranceBps, and let your customer choose another; this helper accepts 1 to 1,000 basis points. The backend module ships the same function whenever its strategy needs a floor.

Fees and sponsorshipCopy Anchor Link

By default the customer's wallet pays each transaction's network fee and the rent for any account it creates:

Rent is separate from the deposit and its yield, and it is not part of earned. Where a request's rent goes when it closes depends on the provider's program; Hastra returns it to the owner. To pay these costs for your customer, sponsor the transaction:

1. Set feePayer to a wallet your backend controls when you build.
2. Have the customer's wallet sign first.
3. Check that the message is unchanged and that its fee payer is your wallet, then add your signature to the same transaction.
4. Submit the transaction with both signatures.

With raw requests, run step 3 on your backend with your fee payer's key pair:

import {
  getAddressFromPublicKey,
  getBase64EncodedWireTransaction,
  getBase64Encoder,
  getCompiledTransactionMessageDecoder,
  getTransactionDecoder,
  partiallySignTransaction,
} from "@solana/kit";

const decode = (base64: string) =>
  getTransactionDecoder().decode(getBase64Encoder().encode(base64));

/** Adds your fee payer's signature to a transaction the customer's wallet signed. */
export async function cosignAsFeePayer(
  unsignedBase64: string,
  customerSignedBase64: string,
  feePayer: CryptoKeyPair,
): Promise<string> {
  const unsigned = decode(unsignedBase64);
  const signed = decode(customerSignedBase64);
  const unchanged =
    signed.messageBytes.length === unsigned.messageBytes.length &&
    signed.messageBytes.every((byte, index) => byte === unsigned.messageBytes[index]);
  if (!unchanged) throw new Error("The wallet changed the transaction; build a new one");

  // The fee payer is the message's first account.
  const { staticAccounts } = getCompiledTransactionMessageDecoder().decode(signed.messageBytes);
  if (staticAccounts[0] !== (await getAddressFromPublicKey(feePayer.publicKey))) {
    throw new Error("This build's fee payer is not your wallet");
  }
  return getBase64EncodedWireTransaction(await partiallySignTransaction([feePayer], signed));
}

Pass it the build's transaction and the customer's signed transaction, then submit what it returns. A missing sponsor signature fails the submit with 400, and changing the fee payer means a new build and new signatures. The build's sponsored field stays false: it reports whether SDP paid, and SDP never pays for an external wallet. In the backend module, signEarnTransaction runs steps 2 and 3, and createSponsorSigner checks the fee payer before it signs.

• Sponsor only builds your backend started for an authenticated customer.
• Keep your sponsor's SOL balance small, rate-limit sponsored requests, and watch the spend.
• Store the sponsor's key in your secret manager.

The catalog's feeSponsored describes deposits and withdrawals from a Treasury custody wallet. It never applies to a customer's wallet.

A full withdrawal from a Kamino strategy leaves the empty share account open. The customer's wallet can close it to recover the rent; do not promise an automatic refund.

Swap-funded depositsCopy Anchor Link

Set sourceTokenMint to fund a deposit with a different supported stablecoin. SDP adds a Jupiter swap to the deposit's deposit token in the same transaction, so both happen or neither does. Swap routes need mainnet, so you cannot test them in sandbox.

When the two do not fit in one transaction, the build returns requiresSeparateSwap: true with a swap and a followUp instead of transaction:

1. Save the swap's signed bytes, its signature, and the follow-up body.
2. Broadcast the swap yourself and confirm it.
3. Build the follow-up deposit with its original floor and fee payer.

SDP does not record the standalone swap as a movement, so your app owns its recovery. Resolve an unfinished swap before you start another.

Retry safelyCopy Anchor Link

Every Earn submit takes an Idempotency-Key. Use a new random UUID for each new deposit, withdrawal, request, or cancellation, and save it with the signed transaction before the first send. Never put customer data in an idempotency key.

Earn's submits keep their own idempotency rules, which replace the shared Idempotency page's. A submit without a key returns 400 BAD_REQUEST, and a misused key returns 409 CONFLICT, never 422. A key stays bound to its movement for good, with no 24-hour window, so never reuse one for a new action.

Submit withdrawal requests and cancellations through SDP promptly. If a wallet broadcasts one itself and SDP first sees it after its build expires, SDP may be unable to track it. Keep unresolved actions visible, and never assume no funds moved.

ErrorsCopy Anchor Link

Every error has the shape { "error": { "code", "message", "details" } }. The codes Earn integrations meet most:

See Errors for the shared error model.

Poll politelyCopy Anchor Link

Track a movement by polling its GET route about once a second for the first minute, then every five seconds. Stop at finalized or failed, and treat 429 as a signal to slow down. Withdrawal requests can take hours or days, so poll them every minute or two, and restore them on startup instead of holding a loop open. The backend module's wait functions follow this schedule. See Rate limits.