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

# SuperSwap

> Cross-chain swap protocol — bridge any token across chains

# SuperSwap

SuperSwap is Hypermid's dedicated cross-chain bridge and swap protocol. It enables token swaps between SuperSwap-supported chains using the same Hypermid API endpoints.

<Note>
  SuperSwap cross-chain is powered by **SuperSwap V2** — an EIP-2535 Diamond
  (`SwapAndBridge` + settlement facets) over Hyperlane Warp Routes. The swap,
  bridge, and any destination unwrap (e.g. WPLS → native PLS) execute from a
  **single signed transaction** to the source-chain DiamondShell — so most swaps
  are one step. Approve `estimate.approvalAddress` for ERC20 inputs, then
  broadcast `transactionRequest`. The status vocabulary is `NOT_FOUND → PENDING →
    DONE | FAILED` (see [Check Status](/api-reference/status)).
</Note>

## Supported Chains

| Chain      | Chain ID | Status     |
| ---------- | -------- | ---------- |
| PulseChain | 369      | **Active** |
| Ethereum   | 1        | **Active** |
| Base       | 8453     | **Active** |
| Arbitrum   | 42161    | **Active** |
| Polygon    | 137      | **Active** |
| Optimism   | 10       | **Active** |
| Unichain   | 130      | **Active** |

Additional chains can be added via Hyperlane Warp Routes — talk to us if your ecosystem is a fit.

## Endpoints You'll Use

| Step | Endpoint                                                                         | Purpose                                                         |
| ---- | -------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| 1    | [`GET /v1/quote`](/api-reference/quote)                                          | Get the swap price and route                                    |
| 2    | [`POST /v1/execute`](/api-reference/execute)                                     | Get transaction data to sign                                    |
| 3    | [`GET /v1/status`](/api-reference/status)                                        | Track swap progress                                             |
| 3b   | [`POST /v1/inbound-receiver/register`](/api-reference/register-inbound-receiver) | Register inbound deposit *(only needed for inbound multi-step)* |

***

## Inbound Swaps (Any Chain → PulseChain)

Inbound swaps deliver tokens to PulseChain. There are two types depending on the source token.

### Inbound — Single Step

**When:** The source token is USDC on a supported chain (Base, Ethereum, Arbitrum, etc.)

**User signs:** 1 transaction

**How it works:** USDC is bridged directly to PulseChain and swapped to the desired token. One signature, fully automatic.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // USDC on Base → PLS on PulseChain (single step)
  const quote = await client.getQuote({
    fromChain: 8453,          // Base
    toChain: 369,             // PulseChain
    fromToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
    toToken: "0xA1077a294dDE1B09bB078844df40758a5D0f9a27",   // PLS
    fromAmount: "5000000",    // $5 USDC
    fromAddress: "0xYourWallet",
    slippage: 0.03,
  });

  // Sign and broadcast — that's it
  const tx = await wallet.sendTransaction(quote.transactionRequest);
  ```

  ```bash cURL theme={"system"}
  curl "https://api.hypermid.io/v1/quote?\
  fromChain=8453&toChain=369&\
  fromToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&\
  toToken=0xA1077a294dDE1B09bB078844df40758a5D0f9a27&\
  fromAmount=5000000&fromAddress=0xYourWallet&slippage=0.03"
  ```
</CodeGroup>

### Inbound — Multi-Step

**When:** The source token is NOT USDC (e.g., ETH, WBTC, or any token on any chain)

**User signs:** 1 transaction + 1 gasless wallet signature (confirmation)

**How it works:** Hypermid first swaps the source token to USDC, then bridges to PulseChain. After the swap transaction confirms, the user signs a gasless confirmation message so Hypermid can route the funds.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // ETH on Base → PLS on PulseChain (multi-step)
  const quote = await client.getQuote({
    fromChain: 8453,
    toChain: 369,
    fromToken: "0x0000000000000000000000000000000000000000", // ETH
    toToken: "0xA1077a294dDE1B09bB078844df40758a5D0f9a27",  // PLS
    fromAmount: "1000000000000000", // 0.001 ETH
    fromAddress: "0xYourWallet",
    slippage: 0.03,
  });

  // Step 1: Sign the swap transaction
  const txHash = await wallet.sendTransaction(
    quote.steps[0].transactionRequest
  );
  await publicClient.waitForTransactionReceipt({ hash: txHash });

  // Step 2: Confirm the deposit (gasless — no transaction fee)
  // The quote response includes afterStep1 with the signing instructions
  if (quote.afterStep1) {
    const signature = await wallet.signTypedData({
      ...quote.afterStep1.eip712,
      message: { ...quote.afterStep1.eip712.message, txHash },
    });

    await fetch(quote.afterStep1.action, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        ...quote.afterStep1.body,
        txHash,
        signature,
      }),
    });
  }

  // Done — Hypermid bridges and swaps automatically (~5-7 min)
  ```

  ```bash cURL theme={"system"}
  # Step 1: Get quote
  curl "https://api.hypermid.io/v1/quote?\
  fromChain=8453&toChain=369&\
  fromToken=0x0000000000000000000000000000000000000000&\
  toToken=0xA1077a294dDE1B09bB078844df40758a5D0f9a27&\
  fromAmount=1000000000000000&\
  fromAddress=0xYourWallet&slippage=0.03"

  # Step 2: Sign the transaction from steps[0].transactionRequest
  # Step 3: Sign the afterStep1.eip712 message and POST to afterStep1.action
  ```
</CodeGroup>

<Tip>
  **How do I know if it's single or multi-step?** Check the quote response:

  * If it has a `transactionRequest` at the top level → **single step**
  * If it has `steps` array and `afterStep1` → **multi-step**
</Tip>

***

## Outbound Swaps (PulseChain → Any Chain)

Outbound swaps send tokens from PulseChain to another chain. The user always signs just one transaction on PulseChain.

<h3 id="outbound-direct-usdch">
  Outbound — Direct USDCh Bridge (fee-free)
</h3>

**When:** Source is USDCh (`0xa5B0D537CeBE97f087Dc5FE5732d70719caaEc1D`) AND destination is canonical USDC on the target chain.

**User signs:** 1 transaction on PulseChain (+ 1 approval if first use)

**How it works:** USDCh on PulseChain is itself a Hyperlane Warp Route (EvmHypSynthetic), so the API builds a direct `transferRemote()` call on the token contract. No Piteas DEX step, no Hypermid Sender contract, no protocol fee — **the user receives USDC 1:1 minus only the Hyperlane gas payment (in PLS)**.

<Note>
  This is the fastest and cheapest possible outbound from PulseChain. The approval is "token approves itself" — `usdch.approve(USDCH_ADDRESS, amount)` — because the EvmHypSynthetic contract IS the token.
</Note>

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // USDCh on PulseChain → USDC on Base (direct, no fee)
  const quote = await client.getQuote({
    fromChain: 369,
    toChain:   8453,
    fromToken: "0xa5B0D537CeBE97f087Dc5FE5732d70719caaEc1D", // USDCh
    toToken:   "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
    fromAmount: "10000000", // 10 USDCh (6 decimals)
    fromAddress: "0xYourWallet",
  });

  // quote.quote.feeBreakdown.totalFeeBps === 0
  // quote.quote.estimatedOutput === "10000000"  (1:1)
  // quote.quote.transactionRequest.to === USDCh address (Warp Route)
  // quote.quote.transactionRequest.value === Hyperlane gas in PLS

  const tx = await wallet.sendTransaction(quote.quote.transactionRequest);
  // USDC arrives on Base in ~3 minutes
  ```

  ```bash cURL theme={"system"}
  curl "https://api.hypermid.io/v1/quote?\
  fromChain=369&toChain=8453&\
  fromToken=0xa5B0D537CeBE97f087Dc5FE5732d70719caaEc1D&\
  toToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&\
  fromAmount=10000000&\
  fromAddress=0xYourWallet"
  ```
</CodeGroup>

Supported destinations: Ethereum (1), Optimism (10), Polygon (137), Base (8453), Arbitrum (42161), Unichain (130).

### Outbound — Single Step

**When:** Source is NOT USDCh (e.g. PLS, HEX) AND destination is USDC.

**User signs:** 1 transaction on PulseChain

**How it works:** Source token is swapped to USDCh via Piteas, routed through the Hypermid OutboundSender contract, and canonical USDC arrives on the destination chain.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // PLS on PulseChain → USDC on Base (single step)
  const quote = await client.getQuote({
    fromChain: 369,           // PulseChain
    toChain: 8453,            // Base
    fromToken: "0xA1077a294dDE1B09bB078844df40758a5D0f9a27", // PLS
    toToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  // USDC on Base
    fromAmount: "200000000000000000000000", // 200,000 PLS
    fromAddress: "0xYourWallet",
    slippage: 0.03,
  });

  // Sign and broadcast — USDC arrives on Base in ~3-5 minutes
  const tx = await wallet.sendTransaction(quote.transactionRequest);
  ```

  ```bash cURL theme={"system"}
  curl "https://api.hypermid.io/v1/quote?\
  fromChain=369&toChain=8453&\
  fromToken=0xA1077a294dDE1B09bB078844df40758a5D0f9a27&\
  toToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&\
  fromAmount=200000000000000000000000&\
  fromAddress=0xYourWallet&slippage=0.03"
  ```
</CodeGroup>

### Outbound — Multi-Step

**When:** The destination token is NOT USDC (e.g., ETH, WBTC, or any non-stablecoin)

**User signs:** 1 transaction on PulseChain

**How it works:** PLS is swapped to a stablecoin, bridged to the destination chain, then swapped to the desired token. The user still signs only one transaction — the backend handles the destination swap automatically.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // PLS on PulseChain → ETH on Base (multi-step, still 1 signature)
  const quote = await client.getQuote({
    fromChain: 369,
    toChain: 8453,
    fromToken: "0xA1077a294dDE1B09bB078844df40758a5D0f9a27", // PLS
    toToken: "0x0000000000000000000000000000000000000000",    // ETH on Base
    fromAmount: "200000000000000000000000",
    fromAddress: "0xYourWallet",
    slippage: 0.03,
  });

  // Sign and broadcast — ETH arrives on Base in ~5-7 minutes
  const tx = await wallet.sendTransaction(quote.transactionRequest);
  ```

  ```bash cURL theme={"system"}
  curl "https://api.hypermid.io/v1/quote?\
  fromChain=369&toChain=8453&\
  fromToken=0xA1077a294dDE1B09bB078844df40758a5D0f9a27&\
  toToken=0x0000000000000000000000000000000000000000&\
  fromAmount=200000000000000000000000&\
  fromAddress=0xYourWallet&slippage=0.03"
  ```
</CodeGroup>

<Tip>
  **Outbound is always 1 signature.** Unlike inbound multi-step, outbound multi-step doesn't require a confirmation step — the backend handles the destination swap automatically.
</Tip>

***

## Universal Code (Handles All Cases)

This single function handles all four swap types:

```typescript theme={"system"}
async function superSwap(params: {
  fromChain: number;
  toChain: number;
  fromToken: string;
  toToken: string;
  fromAmount: string;
  fromAddress: string;
}) {
  // 1. Get quote (throws HypermidError on failure)
  const quote = await client.getQuote({ ...params, slippage: 0.03 });

  // 2. Sign the transaction
  const txRequest = quote.steps?.[0]?.transactionRequest
    || quote.transactionRequest;
  const txHash = await wallet.sendTransaction(txRequest);
  await publicClient.waitForTransactionReceipt({ hash: txHash });

  // 3. Confirm deposit if needed (only inbound multi-step)
  if (quote.afterStep1) {
    const signature = await wallet.signTypedData({
      ...quote.afterStep1.eip712,
      message: { ...quote.afterStep1.eip712.message, txHash },
    });
    await fetch(quote.afterStep1.action, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ ...quote.afterStep1.body, txHash, signature }),
    });
  }

  // 4. Track status
  while (true) {
    const status = await client.getStatus({
      txHash, fromChain: params.fromChain, toChain: params.toChain,
    });
    if (status.status === "DONE") return status;
    if (status.status === "FAILED") throw new Error("Swap failed");
    await new Promise(r => setTimeout(r, 10000));
  }
}

// Usage — same function for all 4 swap types:
await superSwap({ fromChain: 8453, toChain: 369, fromToken: "0x833...", toToken: "0xA10...", fromAmount: "5000000", fromAddress: "0xYou" });
await superSwap({ fromChain: 369, toChain: 8453, fromToken: "0xA10...", toToken: "0x833...", fromAmount: "200000...", fromAddress: "0xYou" });
```

***

## Timing

| Swap Type              | Estimated Time |
| ---------------------- | -------------- |
| Inbound — Single Step  | \~3-5 minutes  |
| Inbound — Multi-Step   | \~5-7 minutes  |
| Outbound — Single Step | \~3-5 minutes  |
| Outbound — Multi-Step  | \~5-7 minutes  |

If the destination swap isn't available after 3 retries, the bridged stablecoin is returned to the user automatically.

## Pricing

All fees are included in the quote. `estimate.toAmount` is what you receive — no hidden costs.

| Route                                      | Hypermid fee      | DEX slippage               | Hyperlane gas                    |
| ------------------------------------------ | ----------------- | -------------------------- | -------------------------------- |
| Inbound (any → PulseChain)                 | Per partner terms | On Piteas leg              | Paid from input                  |
| Outbound single-step (non-USDCh → USDC)    | Per partner terms | On Piteas leg              | Paid from input                  |
| Outbound multi-step (non-USDCh → non-USDC) | Per partner terms | On both Piteas + LiFi legs | Paid from input                  |
| **Outbound direct (USDCh → USDC)**         | **0%**            | None (1:1 bridge)          | Paid in PLS by user (native gas) |

Fee terms are negotiated per partner — contact the team for your account's rates. The direct USDCh → USDC path is fee-free regardless because the user interacts with the Hyperlane Warp Route contract directly — no Hypermid smart contract is in the path.

## Status Values

| Status    | SubStatus                   | Description                            |
| --------- | --------------------------- | -------------------------------------- |
| `PENDING` | `WAIT_SOURCE_CONFIRMATIONS` | Transaction submitted                  |
| `PENDING` | `BRIDGE_IN_PROGRESS`        | Cross-chain transfer (\~3-5 min)       |
| `PENDING` | `SWAP_IN_PROGRESS`          | DEX swap on destination chain          |
| `DONE`    | `COMPLETED`                 | Tokens delivered to user               |
| `DONE`    | `FALLBACK_SENT`             | Swap unavailable — stablecoin returned |
| `FAILED`  | `BRIDGE_TIMEOUT`            | Bridge didn't complete in 30 min       |

## Popular PulseChain Tokens

| Token      | Symbol | Decimals |
| ---------- | ------ | -------- |
| PulseChain | PLS    | 18       |
| HEX        | HEX    | 8        |
| PulseX     | PLSX   | 18       |
| Incentive  | INC    | 18       |
| Hedron     | HDRN   | 9        |
| Tether USD | USDT   | 6        |
| Dai        | DAI    | 18       |

<Note>
  For PLS, use the WPLS address `0xA1077a294dDE1B09bB078844df40758a5D0f9a27` or the zero address. The API handles both.
</Note>