> ## Documentation Index
> Fetch the complete documentation index at: https://core.vanish.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Common questions about integrating Vanish Core.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/vanish/BannerTwitter3(1).png" alt="Dark Sv" />

<Info>
  For the full implementation walkthrough, see the [Integration Guide](/guide/integration). For code examples, see the [Quickstart](/guide/quickstart).
</Info>

## Getting Started

<AccordionGroup>
  <Accordion title="How do we get an API key?">
    API keys are provisioned during onboarding. Contact the Vanish team via [Discord](https://discord.gg/vanishtrade) to get started. Keys are scoped to your team and should be kept server-side - never expose them in client-side code.
  </Accordion>

  <Accordion title="What tokens are supported?">
    Vanish supports native SOL and any SPL token. Pass `11111111111111111111111111111111` for native SOL. For SPL tokens, pass the token mint address. Token support is not restricted by Vanish - any token tradeable on Titan or Jupiter can be used.
  </Accordion>

  <Accordion title="What DEX aggregators can we use to build the swap route?">
    Any DEX aggregator that outputs a standard Solana transaction body. Titan is the primary recommended aggregator. Jupiter is also supported. Your swap instructions are passed through unchanged - Vanish Core wraps them in its own transaction layer.
  </Accordion>

  <Accordion title="What fee does Vanish Core charge? ">
    Vanish Core automatically deducts a 50bps protocol fee at settlement. If you would like to enable fees, speak to the Vanish team  to configure your fee address and basis points.
  </Accordion>
</AccordionGroup>

***

## Deposits

<AccordionGroup>
  <Accordion title="Do I need to deposit before trading?">
    Yes. A Vanish balance is required before any trade can be executed. Call [`GET /deposit_address`](/api-reference/funds/deposit_address) to get the deposit address for the token you want to fund with, transfer on-chain, then call [`POST /commit`](/api-reference/commit) with the confirmed transaction signature. Once the commit returns `completed`, your balance is available for trading.

    See [Fund Your Account](/guide/quickstart#4-fund-your-account) in the Quickstart for a full code example.
  </Accordion>

  <Accordion title="How do deposit addresses work?">
    Each call to [`GET /deposit_address`](/api-reference/funds/deposit_address) returns the current deposit address for a given token. Always fetch a fresh address before each deposit - addresses may rotate based on the token and Vanish's routing to ensure maximum privacy.
  </Accordion>

  <Accordion title="What happens after I transfer funds on-chain?">
    Once the transfer is confirmed on-chain, call [`POST /commit`](/api-reference/commit) with the transaction signature. Vanish will verify the transaction and update your balance.

    * `completed` - balance updated, ready to trade
    * `pending` - compliance screening in progress, check back shortly
    * `rejected` - deposit failed screening, funds will be refunded automatically to the originating wallet
  </Accordion>

  <Accordion title="How do I know if a deposit was rejected?">
    Check the `status` field in the [`/commit`](/api-reference/commit) response. A `rejected` status means the deposit failed compliance or risk screening. Do not re-attempt the deposit - funds will be refunded to the originating wallet automatically after extended screening is completed.
  </Accordion>
</AccordionGroup>

***

## Creating a Trade

<AccordionGroup>
  <Accordion title="How do we create a one-time wallet?">
    Call [`GET /trade/one-time-wallet`](/api-reference/trade/one-time-wallet) - Vanish Core returns a fresh single-use Solana wallet address. You do not generate this yourself. Set the returned address as the signer for all swap instructions in your transaction before submitting.
  </Accordion>

  <Accordion title="Can I reuse a one-time wallet?">
    No. Each address returned by [`GET /trade/one-time-wallet`](/api-reference/trade/one-time-wallet) is single-use. Fetch a fresh one for every trade - reusing a one-time wallet will cause the trade to fail.
  </Accordion>

  <Accordion title="Should I sign the transaction before sending it to /trade/create?">
    No. Submit an **unsigned** transaction in `swap_transaction`. Vanish Core signs and wraps it. Sending a pre-signed transaction will cause it to fail.
  </Accordion>

  <Accordion title="What format does swap_transaction need to be in?">
    A base64-encoded **unsigned** Solana transaction, with the one-time wallet address set as the signer for all swap instructions. Do not add any extra instructions - Vanish Core wraps the transaction and returns the full signed version.
  </Accordion>

  <Accordion title="How does Vanish wrap my swap transaction?">
    Vanish Core wraps your swap instructions inside its own transaction, advancing the required funds to the one-time wallet to execute the trade. If any instruction fails, all operations revert atomically - you are never left with partial state.

    The one-time wallet must be a regular Solana wallet (not an ATA) and must be set as the signer for all swap instructions.
  </Accordion>

  <Accordion title="What does Vanish Core return after /trade/create?">
    On the **Jito route** (default), Vanish Core returns `tx_id` + `jito_bundle_id`. No broadcast is required - Vanish handles it.

    On the **non-Jito route**, Vanish Core returns a fully signed `transaction` payload. Broadcast this through your own RPC.
  </Accordion>

  <Accordion title="What value should I use for split_repay?">
    Start with `1` for most trades. Only increase it if `amount_out` exceeds 0.5% of the token's total supply, which may require spreading holdings across multiple Trading Accounts. Maximum is `9`.

    On the non-Jito route, always use `1` - higher values add more account metas and instructions, increasing the risk of exceeding Solana's transaction size limit.
  </Accordion>

  <Accordion title="What happens if the trade fails on-chain?">
    All operations revert atomically. Failed transactions only cost the base network fee.

    You must still call [`POST /commit`](/api-reference/commit) with the failed transaction's `tx_id` to release the user's balance from its pending state.
  </Accordion>

  <Accordion title="Can we verify the transaction before broadcasting?">
    Yes. On the non-Jito route, Vanish returns the complete signed transaction bytes. Deserialise it and inspect the instruction list before broadcasting to confirm:

    * Your original swap instructions are present and unchanged
    * Only Vanish's injected instructions were added
    * No unauthorised modifications were made
  </Accordion>
</AccordionGroup>

***

## Routing

<AccordionGroup>
  <Accordion title="What is the difference between Jito and non-Jito routing?">
    **Jito (default):** Vanish builds, signs, and broadcasts via a Jito bundle. You receive a `tx_id` and `jito_bundle_id` - no broadcast needed before committing. Best for most trades and high-value amounts where MEV protection matters.

    **Non-Jito:** Vanish returns a fully-signed `transaction` that you broadcast yourself via your own RPC. Use this if you want custom retry logic, a low-latency node, or full control over submission.
  </Accordion>

  <Accordion title="How do I use the non-Jito route?">
    Include the `prefer_non_jito` object in your [`/trade/create`](/api-reference/trade/create) request body. Set `compute_unit_price` and `compute_unit_limit` inside it. Omitting `prefer_non_jito` entirely routes via Jito by default.

    See the [Non-Jito Variant](/guide/quickstart#8-non-jito-variant-self-broadcast) in the Quickstart for a full code example.
  </Accordion>

  <Accordion title="What Jito tip should I set?">
    The minimum recommended tip is `1,000,000` lamports (0.001 SOL). Higher tips increase the likelihood of bundle inclusion during periods of network congestion.
  </Accordion>

  <Accordion title="How do priority fees work on the non-Jito route?">
    Set `compute_unit_price` and `compute_unit_limit` inside the `prefer_non_jito` object. Vanish Core preserves your compute budget settings when wrapping the transaction.
  </Accordion>
</AccordionGroup>

***

## Withdrawals

<AccordionGroup>
  <Accordion title="Can a user withdraw to a different wallet than the one they deposited from?">
    No. Vanish enforces a strict **same wallet in, same wallet out** model. Withdrawals are always routed back to the wallet that made the original deposit. This is required by Vanish's AML framework and cannot be bypassed.
  </Accordion>

  <Accordion title="What is additional_sol in the withdraw request?">
    It covers the lamport cost of creating a token account (ATA) at the destination wallet if one doesn't already exist. If the destination already has an ATA for the token being withdrawn, a lower value may work - but use a safe default to avoid failures.
  </Accordion>
</AccordionGroup>

***

## Authentication & Signing

<AccordionGroup>
  <Accordion title="How do we authenticate API calls?">
    All API endpoints require an `x-api-key` header. Keys are provisioned during onboarding and should never be exposed in client-side code.
  </Accordion>

  <Accordion title="How does request signing work?">
    Write operations ([`/trade/create`](/api-reference/trade/create), [`/withdraw/create`](/api-reference/funds/withdraw)) and read operations ([`/account/balances`](/api-reference/account/get_balances), [`/account/pending`](/api-reference/account/get_pending_actions), etc.) require a user-signed message proving ownership of `user_address`.

    Sign with the user's Solana keypair (Ed25519) and base64-encode the result. The message format varies by endpoint - see [Signing Requests](/guide/integration#signing-requests) for the exact format for each operation.

    Timestamps must be Unix time in **milliseconds**. Stale timestamps are rejected to prevent replay attacks.
  </Accordion>

  <Accordion title="What is the most common cause of 401 errors?">
    Malformed signatures. The most frequent issues are:

    * Using seconds instead of milliseconds for the timestamp
    * Missing or incorrect newlines in the message string
    * Base58 or hex encoding instead of base64
    * Signing with the wrong keypair

    See [Error Handling - 401](/guide/handling#handling-401---signature-errors) for a full checklist.
  </Accordion>
</AccordionGroup>

***

## Commit & Balances

<AccordionGroup>
  <Accordion title="Why must /commit be called even for failed transactions?">
    Vanish Core places a portion of the user's balance in a pending state when a transaction is submitted. Calling [`/commit`](/api-reference/commit) - with any outcome - tells Vanish Core to resolve that balance, either applying the change or reverting it. Without a commit, the balance remains in a pending state indefinitely.
  </Accordion>

  <Accordion title="What happens if I never call /commit?">
    The user's balance remains in a pending state. Use [`POST /account/pending`](/api-reference/account/get_pending_actions) on startup to detect any transactions awaiting commit - for example, after a crash or timeout. Call [`/commit`](/api-reference/commit) with each returned `tx_id` to resolve them. [`/commit`](/api-reference/commit) is idempotent and safe to retry.
  </Accordion>

  <Accordion title="What statuses can /commit return?">
    | Status      | Meaning                                                                                                                             |
    | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
    | `completed` | Action processed successfully: the user's Vanish balance has been updated                                                           |
    | `rejected`  | Deposit failed compliance or risk screening: funds will be refunded to the originating wallet after extended screening is completed |
    | `pending`   | Waiting for the transaction to land on-chain or undergo compliance screening: check back shortly                                    |
    | `failed`    | The transaction was rejected on-chain: the user's balance is no longer in a pending state                                           |
    | `expired`   | The transaction was not confirmed within the required window: the user's balance is no longer in a pending state                    |
  </Accordion>

  <Accordion title="What does already_processed mean in the commit response?">
    If `already_processed: true`, this `tx_id` was already committed in a previous call. The response still contains the correct `status` and `balance_changes`. This is by design - [`/commit`](/api-reference/commit) is idempotent and safe to retry.
  </Accordion>
</AccordionGroup>

***

## Fees & Network

<AccordionGroup>
  <Accordion title="What is loan_additional_sol and how should we set it?">
    We recommend `12000000` lamports (`0.012 SOL`) for `loan_additional_sol` - this covers ATA creation costs during the trade. Any unused amount is automatically refunded after settlement.

    If the target token's ATA already exists in the user's wallet, a lower value may work - but the recommended value is safe for all cases.
  </Accordion>

  <Accordion title="How does platform fee sharing work?">
    Platform fees are deducted within the swap instruction and factored into settlement. Vanish Core automatically deducts its 50bps protocol fee at settlement. Speak to the Vanish team during onboarding to configure your fee address and basis points.
  </Accordion>

  <Accordion title="What is the expected latency overhead?">
    The injection process adds approximately **200ms** to trade finality on top of your existing RPC or node submission time.
  </Accordion>

  <Accordion title="How do I convert between SOL and lamports?">
    1 SOL = 1,000,000,000 lamports. All SOL amounts in the Vanish API are in lamports. SPL token amounts use the token's own decimal precision.
  </Accordion>
</AccordionGroup>

***

## Compliance

<AccordionGroup>
  <Accordion title="What is the same-wallet-in, same-wallet-out rule?">
    Vanish enforces a strict compliance model: funds can only be withdrawn to the same wallet they were deposited from. Users cannot redirect funds to a different address. This is required by Vanish's AML framework and ensures a clear, auditable trail for all fund movements.
  </Accordion>

  <Accordion title="What happens when a deposit is rejected?">
    A `rejected` commit status means the deposit failed compliance or risk screening. Funds will be refunded to the originating wallet after extended screening is completed. Do not re-attempt the deposit until the refund is confirmed.
  </Accordion>
</AccordionGroup>

***

<Info>
  Experiencing an issue not covered here? Join us on [Discord](https://discord.gg/vanishtrade) - our engineers are available to help.
</Info>