> ## 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.

# Get Status

> Check the status of a swap transaction

Returns the current status of a cross-chain swap transaction. Use this to track the progress of swaps after the user has signed and submitted the transaction.

<ParamField query="txHash" type="string" required>
  The transaction hash on the source chain.
</ParamField>

<ParamField query="fromChain" type="number" required>
  Source chain ID.
</ParamField>

<ParamField query="toChain" type="number" required>
  Destination chain ID.
</ParamField>

<ParamField query="bridge" type="string">
  The bridge/tool used. If not provided, Hypermid will auto-detect.
</ParamField>

<ResponseExample>
  ```json 200 DONE theme={"system"}
  {
    "data": {
      "status": "DONE",
      "subStatus": "COMPLETED",
      "sending": {
        "txHash": "0xSourceTransactionHash",
        "chainId": 1,
        "amount": "1000000000000000000",
        "token": {
          "symbol": "ETH",
          "address": "0x0000000000000000000000000000000000000000"
        },
        "gasUsed": "150000",
        "gasPrice": "20000000000",
        "timestamp": 1711234500
      },
      "receiving": {
        "txHash": "0xDestinationTransactionHash",
        "chainId": 42161,
        "amount": "3237500000",
        "token": {
          "symbol": "USDC",
          "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
        },
        "timestamp": 1711234620
      },
      "tool": "stargate",
      "fromAddress": "0xSenderAddress",
      "toAddress": "0xReceiverAddress"
    },
    "error": null,
    "meta": {
      "requestId": "i9d0e1f2-a3b4-5678-2345-789012345678",
      "timestamp": 1711234625,
      "rateLimit": {
        "limit": 2000,
        "remaining": 1991,
        "reset": 1711234627
      }
    }
  }
  ```

  ```json 200 PENDING theme={"system"}
  {
    "data": {
      "status": "PENDING",
      "subStatus": "BRIDGE_IN_PROGRESS",
      "sending": {
        "txHash": "0xSourceTransactionHash",
        "chainId": 1,
        "amount": "1000000000000000000",
        "token": { "symbol": "ETH" },
        "timestamp": 1711234500
      },
      "receiving": null,
      "tool": "stargate"
    },
    "error": null,
    "meta": {
      "requestId": "j0e1f2a3-b4c5-6789-3456-890123456789",
      "timestamp": 1711234560,
      "rateLimit": {
        "limit": 2000,
        "remaining": 1990,
        "reset": 1711234627
      }
    }
  }
  ```
</ResponseExample>

### Status Values

| Status      | Description                              |
| ----------- | ---------------------------------------- |
| `NOT_FOUND` | Transaction not found or not yet indexed |
| `PENDING`   | Transaction is being processed           |
| `DONE`      | Swap completed successfully              |
| `FAILED`    | Swap failed                              |

### Sub-Status Values

| Sub-Status                     | Description                               |
| ------------------------------ | ----------------------------------------- |
| `WAIT_SOURCE_CONFIRMATIONS`    | Waiting for source chain confirmations    |
| `BRIDGE_IN_PROGRESS`           | Bridge transfer is in progress            |
| `WAIT_DESTINATION_TRANSACTION` | Waiting for destination chain transaction |
| `COMPLETED`                    | Fully completed                           |
| `PARTIAL`                      | Partially completed (refund may follow)   |
| `REFUNDED`                     | Transaction was refunded                  |

### SuperSwap Status Values

SuperSwap cross-chain swaps are powered by **SuperSwap V2** (an EIP-2535 Diamond
plus Hyperlane Warp Routes). Add `provider=superswap` to the query when polling.
The `status` field uses the same top-level vocabulary as the rest of `/v1/status`:

| Status      | Description                                                     | Terminal? |
| ----------- | --------------------------------------------------------------- | --------- |
| `NOT_FOUND` | Source tx not yet indexed — keep polling                        | no        |
| `PENDING`   | Bridge + destination settlement in progress                     | no        |
| `DONE`      | Output token delivered to the recipient                         | yes ✅     |
| `FAILED`    | Unrecoverable failure — funds recoverable via the fallback path | yes ❌     |
| `INVALID`   | Malformed request (bad hash / chain)                            | yes ❌     |

The response also carries `sending` / `receiving` legs (source + destination tx
info) and `hyperlaneMessageId` (stable across both legs). Suggested poll
interval: 5 seconds; typical time to `DONE` is \~2 minutes. Stop polling once a
terminal status is reached.

```typescript theme={"system"}
// Poll until terminal
while (true) {
  const { data } = await client.getStatus({
    provider: "superswap",
    txHash,
    fromChain,
    toChain,
  });
  if (["DONE", "FAILED", "INVALID"].includes(data.status)) break;
  await new Promise(r => setTimeout(r, 5000));
}
```

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const status = await client.getStatus({
    txHash: "0xSourceTransactionHash",
    fromChain: 1,
    toChain: 42161,
  });

  switch (status.data.status) {
    case "DONE":
      console.log("Complete! Received:", status.data.receiving.amount);
      break;
    case "PENDING":
      console.log("In progress:", status.data.subStatus);
      break;
    case "FAILED":
      console.log("Failed");
      break;
    case "NOT_FOUND":
      console.log("Not found yet — try again shortly");
      break;
  }
  ```

  ```bash cURL theme={"system"}
  curl "https://api.hypermid.io/v1/status?\
  txHash=0xSourceTransactionHash&\
  fromChain=1&\
  toChain=42161" \
    -H "X-API-Key: your-api-key"
  ```

  ```go Go theme={"system"}
  url := "https://api.hypermid.io/v1/status?" +
      "txHash=0xSourceTransactionHash" +
      "&fromChain=1&toChain=42161"

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Set("X-API-Key", "your-api-key")
  resp, _ := http.DefaultClient.Do(req)
  ```
</CodeGroup>

<Tip>
  For manual deposit routes, use [GET /v1/execute/deposit/status](/api-reference/deposit-status) instead.
</Tip>

## SuperSwap Refunds & Fallback

For SuperSwap (PulseChain) polls, the terminal states `COMPLETED`, `FALLBACK_SENT`, and `FAILED` each require different UX. In particular `FALLBACK_SENT` is a **success-with-caveat** — the user received bridged USDCh instead of their requested token because the DEX leg couldn't execute; treat it as "swap complete, with a substituted output," not as a failure.

See the [Safety & Fallback guide](/guides/safety-fallback) for the full state machine, every failure scenario, and suggested UI copy for each terminal state.


## OpenAPI

````yaml GET /v1/status
openapi: 3.0.3
info:
  title: Hypermid Partner API
  version: 1.0.0
  description: >-
    Cross-chain swap aggregator API. Supports 30+ EVM chains, Solana, Bitcoin,
    Sui, and Near Intents chains (NEAR, TON, Tron, XRP, etc.).


    ## Authentication

    Pass your API key via the `X-API-Key` header. Public endpoints work without
    a key (anonymous tier). Partner endpoints (`/v1/partner/*`) require a valid
    key.


    ## Rate Limits

    - **Anonymous**: 30 requests/minute (per IP)

    - **Partner (authenticated)**: 100 requests/minute (per API key)


    These limits are designed for human-driven widget usage and mirror our
    upstream aggregator (LiFi) limits to prevent any single user from exhausting
    shared quota.


    Rate limit info is returned in `meta.rateLimit` on every response.


    ## Response Envelope

    All responses follow the shape:

    ```json

    { "data": <T | null>, "error": <{ code, message, details? } | null>, "meta":
    { "requestId", "timestamp", "rateLimit?" } }

    ```
  contact:
    name: Hypermid
    url: https://hypermid.io
servers:
  - url: https://api.hypermid.io
    description: Production
security:
  - ApiKeyAuth: []
  - {}
tags:
  - name: Swap
    description: Cross-chain swap quoting, routing, status, and reference data
  - name: Execute
    description: Transaction execution and deposit management for Near Intents swaps
  - name: On-Ramp
    description: Fiat-to-crypto on-ramp via RampNow
  - name: Partner
    description: Partner account, analytics, and webhook management (requires X-API-Key)
  - name: Tracking
    description: Swap event tracking for partner attribution
  - name: System
    description: Health check and API metadata
paths:
  /v1/status:
    get:
      tags:
        - Swap
      summary: Check swap status
      description: >-
        Check the status of a cross-chain swap.


        - **LI.FI** swaps: pass `txHash` + `bridge` + `fromChain` + `toChain`.
        Returns LI.FI's native status shape.

        - **Near Intents**: pass `provider=near-intents&correlationId=...`.
        Returns the 1Click status.

        - **SuperSwap**: pass
        `provider=superswap&txHash=...&fromChain=...&toChain=369`. Returns a
        status that moves through `INITIATED` → `BRIDGING` → `BRIDGE_CONFIRMED`
        → `SWAPPING` → `COMPLETED`. Terminal failure states are `FAILED`
        (retries exhausted, manual recovery needed) or `FALLBACK_SENT` (DEX swap
        failed after 3 retries — bridged USDCh has been sent to the user's
        wallet as a safety fallback). Suggested poll interval: 5 seconds.
        Typical time-to-COMPLETED is 3–5 minutes. See `/guides/safety-fallback`
        for the full state machine and what each terminal state means.
      operationId: getSwapStatus
      parameters:
        - name: txHash
          in: query
          required: false
          schema:
            type: string
          description: Transaction hash (required for LI.FI + SuperSwap)
        - name: bridge
          in: query
          required: false
          schema:
            type: string
          description: Bridge name (LI.FI swaps)
        - name: fromChain
          in: query
          required: false
          schema:
            type: integer
          description: Source chain ID (LI.FI + SuperSwap)
        - name: toChain
          in: query
          required: false
          schema:
            type: integer
          description: Destination chain ID (LI.FI + SuperSwap — 369 for SuperSwap)
        - name: provider
          in: query
          required: false
          schema:
            type: string
            enum:
              - near-intents
              - superswap
          description: >-
            Set to 'near-intents' or 'superswap' to select the status backend.
            Omit for LI.FI.
        - name: correlationId
          in: query
          required: false
          schema:
            type: string
          description: Correlation ID (required when provider=near-intents)
      responses:
        '200':
          description: Status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '502':
          $ref: '#/components/responses/UpstreamError'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        data:
          description: Response payload (null on error)
        error:
          nullable: true
          type: object
          properties:
            code:
              type: string
              example: INVALID_PARAMS
            message:
              type: string
              example: 'Missing required parameters: fromChain'
            details:
              type: object
              additionalProperties: true
          required:
            - code
            - message
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - data
        - error
        - meta
    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          type: integer
          description: Unix epoch seconds
        rateLimit:
          type: object
          properties:
            limit:
              type: integer
            remaining:
              type: integer
            reset:
              type: integer
              description: Unix epoch seconds when the window resets
      required:
        - requestId
        - timestamp
  responses:
    BadRequest:
      description: Invalid or missing parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
    UpstreamError:
      description: Upstream provider error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Partner API key. Optional for public endpoints, required for
        /v1/partner/*.

````