Get Status

Check the status of a swap transaction

GET /v1/status

Check swap status

cURL

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

200 DONE

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

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.

200 DONE

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

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

For SuperSwap routes (provider=superswap), the status field moves through a specific sequence. Add provider=superswap to the query when polling:

Status	Description	Terminal?
INITIATED	Deposit registered, waiting for bridge	no
BRIDGING	Hyperlane message in flight from source chain	no
BRIDGE_CONFIRMED	Bridge delivered on PulseChain — preparing DEX swap	no
SWAPPING	Piteas DEX swap executing on PulseChain	no
COMPLETED	Output token delivered to the user’s wallet	yes ✅
FAILED	Unrecoverable failure — funds may need manual recovery	yes ❌
FALLBACK_SENT	DEX swap failed — USDCh sent to user as fallback	yes ⚠️

Suggested poll interval: 5 seconds. Typical time to COMPLETED is 3–5 minutes (Hyperlane delivery dominates). Stop polling once a terminal status is reached.

// Poll until complete
while (true) {
  const { data } = await client.getStatus({
    provider: "superswap",
    txHash,
    fromChain,
    toChain,
  });
  if (["COMPLETED", "FAILED", "FALLBACK_SENT"].includes(data.status)) break;
  await new Promise(r => setTimeout(r, 5000));
}

TypeScript

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

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

200

application/json

Status retrieved

data · any · required

Response payload (null on error)

error · object · required

Show child attributes

meta · object · required

Show child attributes