> For the complete documentation index, see [llms.txt](https://docs.swapper.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapper.finance/api-v1/endpoints/status.md).

# Status

```
GET /v1/status
```

Looks up a transfer by any of its transaction hashes — source or destination — and refreshes it while it's in flight. Poll it after the user broadcasts the [quoted](https://docs.swapper.finance/api-v1/endpoints/quote.md) transaction until the transfer settles.

It also finds transfers into a [deposit address](https://docs.swapper.finance/api-v1/endpoints/deposit-addresses.md) — by any of their hashes, including the user's own transfer into the address (the hash they see in their wallet or exchange history).

Tracking a transfer here is also what **records** it at Swapper: a transfer only becomes a deposit once something tracks it. That record is what attributes the transfer, and your [integrator fee](https://docs.swapper.finance/api-v1/integrator-fees.md#getting-paid), to your quote, and what triggers your [webhook](#webhooks) — so poll every transfer you quote.

## Parameters

| Name        | Required        | Description                                                                                                  |
| ----------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
| `txHash`    | yes             | A transaction hash of the transfer (EVM `0x…`, or a Solana signature).                                       |
| `fromChain` | no, recommended | Source chain id or key. A transfer Swapper hasn't seen yet can only be found when the source chain is given. |
| `toChain`   | no              | Destination chain id or key (validated, informational).                                                      |

No `integrator` is needed. Send your API key to see your fees on transfers that belong to you (see [below](#your-own-transfers)).

## Example

```bash
curl -G "https://swapper.finance/api/v1/status" \
  --data-urlencode "txHash=0xefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef" \
  --data-urlencode "fromChain=8453"
```

## Response

```json
{
  "transactionId": "0x630e5dd19250dcef53d89aabd3b23e8b37795858d1d66d75ba4e93489204f65b",
  "sending": {
    "txHash": "0xefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef",
    "txLink": "https://basescan.org/tx/0xefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef",
    "amount": "100000000",
    "amountUSD": "100.00",
    "token": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chainId": "8453", "symbol": "USDC", "decimals": 6, "name": "USD Coin", "logoURI": "", "priceUSD": "1" },
    "chainId": "8453",
    "timestamp": 1791054717
  },
  "receiving": {
    "txHash": "0x9999999999999999999999999999999999999999999999999999999999999999",
    "txLink": "https://arbiscan.io/tx/0x9999999999999999999999999999999999999999999999999999999999999999",
    "amount": "99300000",
    "amountUSD": "99.29",
    "token": { "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "chainId": "42161", "symbol": "USDC", "decimals": 6, "name": "USD Coin", "logoURI": "", "priceUSD": "0.9999" },
    "chainId": "42161",
    "timestamp": 1791054717
  },
  "status": "DONE",
  "substatus": "COMPLETED",
  "substatusMessage": "The transfer is complete.",
  "tool": "swapper",
  "toAddress": "0x1111111111111111111111111111111111111111"
}
```

| Field              | Type             | Description                                         |
| ------------------ | ---------------- | --------------------------------------------------- |
| `transactionId`    | string?          | Opaque, stable id of the transfer.                  |
| `sending`          | TransactionInfo  | The source side.                                    |
| `receiving`        | TransactionInfo? | The destination side, once known.                   |
| `status`           | string           | See [statuses](#statuses).                          |
| `substatus`        | string?          | See [statuses](#statuses).                          |
| `substatusMessage` | string?          | Human-readable explanation.                         |
| `tool`             | string           | Always `swapper`.                                   |
| `fromAddress`      | string?          | Sender, when known.                                 |
| `toAddress`        | string?          | Recipient.                                          |
| `integrator`       | string?          | Only for [your own transfers](#your-own-transfers). |
| `feeCosts`         | FeeCost\[]?      | Only for [your own transfers](#your-own-transfers). |

### `TransactionInfo`

| Field       | Type                                                                                          | Description                                                                                                                                                                                          |
| ----------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `txHash`    | string?                                                                                       | Transaction hash.                                                                                                                                                                                    |
| `txLink`    | string?                                                                                       | Block-explorer link.                                                                                                                                                                                 |
| `amount`    | string?                                                                                       | Amount, in the token's smallest unit.                                                                                                                                                                |
| `amountUSD` | string?                                                                                       | USD value — at the time of the transfer, or at today's price when that wasn't recorded. Omitted when the price is unknown.                                                                           |
| `token`     | [Token](https://docs.swapper.finance/api-v1/endpoints/chains-and-tokens.md#the-token-object)? | The token sent or received.                                                                                                                                                                          |
| `chainId`   | string?                                                                                       | Swapper chain id, e.g. `"8453"`. A transfer funded from Bitcoin or Tron (possible through the widget's deposit addresses) reports `"bitcoin"` or `"728126428"`; those chains aren't on `/v1/chains`. |
| `timestamp` | integer?                                                                                      | Unix seconds.                                                                                                                                                                                        |

## Statuses

| `status`    | `substatus`                    | Meaning                                                                                                                                                                                                   |
| ----------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NOT_FOUND` | —                              | Not (yet) known. Retry later, and pass `fromChain`.                                                                                                                                                       |
| `PENDING`   | `WAIT_SOURCE_CONFIRMATIONS`    | The source transaction hasn't settled yet.                                                                                                                                                                |
| `PENDING`   | `WAIT_DESTINATION_TRANSACTION` | On its way to the destination.                                                                                                                                                                            |
| `PENDING`   | `UNKNOWN_ERROR`                | Taking longer than expected; it's being looked into.                                                                                                                                                      |
| `PENDING`   | `REFUND_IN_PROGRESS`           | Couldn't be delivered; Swapper is refunding the tokens to the sender. It doesn't change on its own after the refund — open a ticket in [Discord](https://discord.gg/y8eevERxBz) if you need confirmation. |
| `DONE`      | `COMPLETED`                    | Delivered.                                                                                                                                                                                                |
| `DONE`      | `REFUNDED`                     | Couldn't complete; the tokens were refunded to the sender.                                                                                                                                                |
| `FAILED`    | `UNKNOWN_ERROR`                | Failed — see `substatusMessage`.                                                                                                                                                                          |

Treat `DONE` and `FAILED` as final; keep polling anything else.

**Polling tips:** poll every few seconds while `PENDING`, back off for long cross-chain transfers (use the quote's `estimate.executionDuration` as a guide), and stop at a final status. Status checks count against the **default** [rate limit](https://docs.swapper.finance/api-v1/rate-limits.md), not the quote one.

## Your own transfers

When the request carries the **API key of the integrator the transfer belongs to**, the response also includes `integrator` and `feeCosts` — the Swapper fee and your integrator fee charged on the transfer:

```jsonc
{
  "transactionId": "0x630e5dd19250dcef53d89aabd3b23e8b37795858d1d66d75ba4e93489204f65b",
  "sending": { "txHash": "0xefef…", "chainId": "8453", "amount": "100000000" },
  "status": "DONE",
  "substatus": "COMPLETED",
  "substatusMessage": "The transfer is complete.",
  "tool": "swapper",
  "toAddress": "0x1111111111111111111111111111111111111111",
  "integrator": "acme",
  "feeCosts": [
    {
      "name": "Swapper fee",
      "description": "Swapper's fee for routing the transfer",
      "token": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chainId": "8453", "symbol": "USDC", "decimals": 6 /* … */ },
      "amount": "100000",
      "amountUSD": "0.10",
      "percentage": "0.001",
      "included": true
    },
    {
      "name": "Integrator fee",
      "description": "Fee charged by the integrator",
      "token": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chainId": "8453", "symbol": "USDC", "decimals": 6 /* … */ },
      "amount": "400000",
      "amountUSD": "0.40",
      "percentage": "0.004",
      "included": true
    }
  ]
}
```

Passing an `integrator` parameter doesn't unlock these fields — only the owning integrator's API key does.

## Not found

An unknown transaction is not an error — it returns `200` with `status: "NOT_FOUND"`:

```json
{
  "sending": {
    "txHash": "0x1212121212121212121212121212121212121212121212121212121212121212",
    "chainId": "8453",
    "txLink": "https://basescan.org/tx/0x1212121212121212121212121212121212121212121212121212121212121212"
  },
  "status": "NOT_FOUND",
  "tool": "swapper"
}
```

Right after broadcasting this is normal — retry, and make sure you pass `fromChain`.

## Errors

| Status | Code                | When                                                                     |
| ------ | ------------------- | ------------------------------------------------------------------------ |
| `400`  | `VALIDATION_ERROR`  | `txHash` is missing or malformed.                                        |
| `400`  | `UNSUPPORTED_CHAIN` | `fromChain` or `toChain` isn't served by v1.                             |
| `401`  | `INVALID_API_KEY`   | An unknown or revoked API key was sent.                                  |
| `429`  | `RATE_LIMITED`      | See [Rate Limits](https://docs.swapper.finance/api-v1/rate-limits.md).   |
| `500`  | `INTERNAL_ERROR`    | Unexpected error. Safe to retry.                                         |
| `502`  | `UPSTREAM_ERROR`    | A network or liquidity source is temporarily unavailable. Retry shortly. |

See [Errors](https://docs.swapper.finance/api-v1/errors.md) for the envelope and all codes.

## Webhooks

`/v1/status` is the **pull** view of a transfer. A tracked v1 transfer is recorded through the same pipeline as widget deposits, so when it completes Swapper also **pushes** a `transaction.completed` [webhook](https://docs.swapper.finance/tracking-deposits/webhooks.md) to the endpoints configured in your [Integrator Dashboard](https://docs.swapper.finance/integrator-dashboard/overview.md#webhooks) — with `method: "dex_swap"`, like a widget wallet deposit.

{% hint style="warning" %}
The webhook only fires for transfers Swapper has recorded, and a v1 transfer is recorded when something tracks it. Keep polling `/v1/status` after the user broadcasts — don't rely on the webhook alone.
{% endhint %}
