Get Status

Check swap status

curl --request GET \
  --url https://api.hypermid.io/v1/status \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.hypermid.io/v1/status"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.hypermid.io/v1/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hypermid.io/v1/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hypermid.io/v1/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.hypermid.io/v1/status")
  .header("X-API-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hypermid.io/v1/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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
    }
  }
}

{
  "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
    }
  }
}

GET

status

Check swap status

curl --request GET \
  --url https://api.hypermid.io/v1/status \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.hypermid.io/v1/status"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.hypermid.io/v1/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hypermid.io/v1/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hypermid.io/v1/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.hypermid.io/v1/status")
  .header("X-API-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hypermid.io/v1/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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
    }
  }
}

{
  "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
    }
  }
}

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.

txHash

string

required

The transaction hash on the source chain.

fromChain

number

required

Source chain ID.

toChain

number

required

Destination chain ID.

bridge

string

The bridge/tool used. If not provided, Hypermid will auto-detect.

{
  "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
    }
  }
}

{
  "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
    }
  }
}

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.

// 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));
}

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;
}

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

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)

For manual deposit routes, use GET /v1/execute/deposit/status instead.

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 for the full state machine, every failure scenario, and suggested UI copy for each terminal state.

Authorizations

X-API-Key

string

header

required

Partner API key. Optional for public endpoints, required for /v1/partner/*.

Query Parameters

txHash

string

Transaction hash (required for LI.FI + SuperSwap)

bridge

string

Bridge name (LI.FI swaps)

fromChain

integer

Source chain ID (LI.FI + SuperSwap)

toChain

integer

Destination chain ID (LI.FI + SuperSwap — 369 for SuperSwap)

provider

enum<string>

Set to 'near-intents' or 'superswap' to select the status backend. Omit for LI.FI.

Available options:

near-intents,

superswap

correlationId

string

Correlation ID (required when provider=near-intents)

Response

Status retrieved

data

any

required

Response payload (null on error)

error

object | null

required

Show child attributes

Overview

Discovery

Swap

On-Ramp

Partner

System

Status Values

Sub-Status Values

SuperSwap Status Values

SuperSwap Refunds & Fallback

Authorizations

Query Parameters

Response

​Status Values

​Sub-Status Values

​SuperSwap Status Values

​SuperSwap Refunds & Fallback

Authorizations

Query Parameters

Response

Status Values

Sub-Status Values

SuperSwap Status Values

SuperSwap Refunds & Fallback