# Estimating Swaps

The swap estimation endpoint allows you to estimate the output amount and required messages for a token swap before executing it. Routing includes both native swaps (our gamm module) and routing through Skip:Go across IBC chains like Osmosis.

## Endpoint

```
POST https://api.bitbadges.io/api/v0/api/{version}/swaps/estimate
```

```typescript
export interface iEstimateSwapPayload {
  /** The token in to swap. Format: "amount:X,denom:Y" */
  tokenIn: string;
  /** Optional chain ID for the token in. Defaults to "bitbadges-1" if not provided. */
  tokenInChainId?: string;
  /** The token out denom to swap to. */
  tokenOutDenom: string;
  /** Optional chain ID for the token out. Defaults to "bitbadges-1" if not provided. */
  tokenOutChainId?: string;
  /**
   * Mapping of chain IDs to addresses.
   * Only supports "bitbadges-1" (bech32 bb prefixed address for Cosmos-based chains and "1" (EVM-based chains with a standard 0x address)
   *
   * We will generate any other chain addresses from these addresses.
   */
  chainIdsToAddresses: Record<string, string>;
  /**
   * Optional mapping of chain IDs to affiliate fee recipients.
   * Structure: { [chainId]: { affiliates: Array<{ address: string; basis_points_fee: string }> } }
   */
  chainIdsToAffiliates?: Record<string, { affiliates: Array<{ address: string; basis_points_fee: string }> }>;
  /** Slippage tolerance as a percentage (0-100). Can be a string or number. */
  slippageTolerancePercent: string | number;
  /** Forcefully recheck compliance and avoid cache (5 minutes) */
  forcefulRecheckCompliance?: boolean;
}
```

```typescript
export interface iEstimateSwapSuccessResponse {
  /** Whether the swap estimation was successful. */
  success: boolean;
  /** Detailed estimation information for the swap. */
  estimate: {
    /** The estimated amount of tokens that will be received (token out). */
    tokenOutAmount: string;
    /** The amount of tokens being swapped in (token in). */
    tokenInAmount: string;
    /**
     * Messages for multi-chain routing.
     * Contains either a multi-chain message (for Cosmos chains) or an EVM transaction (for EVM chains).
     * These messages are used to execute the swap across different chains if needed.
     */
    skipGoMsgs: SkipGoMessage[];
    /**
     * The path the asset takes through different chains and operations to complete the swap.
     * Each step in the path indicates the denom, chain ID, and how the asset moves (genesis, swap, or transfer).
     */
    assetPath: {
      denom: string;
      chainId: string;
      how: 'genesis' | 'swap' | 'transfer';
    }[];
    /** Whether an actual swap operation occurs (true) or if it's just a transfer. */
    doesSwap: boolean;
    /** Warning flag indicating if the liquidity pool has low liquidity, which may affect swap execution. */
    lowLiquidityWarning?: boolean;
    /** Warning flag indicating if compliance checks did not pass for this swap. This means swap is likely to fail on BitBadges pool swap with compliance checks. */
    complianceNotPassedWarning?: boolean;
    /** Detailed error message if compliance checks failed. */
    complianceErrorMessage?: string;
    /** Estimated time in seconds for the swap to complete (if available). */
    estimatedTime?: number;
    /** Fallback asset if swap is not possible. */
    fallbackAsset?: { denom: string; chainId: string; };
  };
}
```

## Skip Go Compatibility

We attempt to mirror Skip:Go support as much as possible. And, we plan to eventually get fully integrated directly. However, there are a couple of minor differences and we do not claim full compatibility yet:

* **Limited Skip Support**: Skip doesn't support our routing yet, so their API, engines, explorers, and client might not support the full feature set
* **Message Format**: The `skipGoMsgs` returned attempt to follow the format from the [Skip API](https://docs.skip.build/go/api-reference/prod/fungible/post-v2fungiblemsgs)
* **Cosmos Only**: This route will only recommend Cosmos swaps. For other chains outside of Cosmos liek ETH and SOL, these are not supported yet.

## Example

```typescript
const response = await BitBadgesApi.estimateSwap({
// ...
});

console.log(response.estimate.tokenOutAmount);
console.log(response.estimate.skipGoMsgs);

// Use the msgs to get user signatures and execute the swap
```

## Executing from the CLI

For a **BitBadges-only** route (a single native swap on the BitBadges chain — no Skip:Go rerouting, EVM tx, IBC-transfer leg, or WETH redirect) you can sign + broadcast straight from the CLI without handling `skipGoMsgs` yourself:

```bash
bb swap estimate ubadge uusdc 1000000 --execute --browser
```

Cross-chain / EVM / multi-hop routes are returned but not auto-executed: sign the estimate in your wallet, broadcast the first transaction, then `bb swap track`. See [Swap CLI](/for-developers/cli/standards-commands.md#executing-a-swap-bb-swap-execute).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bitbadges.io/for-developers/bitbadges-api/estimating-swaps.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.