Request Status Codes

When submitting requests with Bungee, monitoring the status of requests is essential. This is a explainer of the different status codes returned by the Bungee API and how to interpret them.

API Reference: Status Endpoint

Checking Request Status

To check the status of a request, you can use the Bungee API endpoint. The request hash can be either:

• The requestHash returned from a submit request (for Auto routes)
• The transaction hash (for Manual routes)

const BUNGEE_API_BASE_URL = "https://public-backend.bungee.exchange";

async function checkStatus(requestHash) {
  try {
    const response = await fetch(
      `${BUNGEE_API_BASE_URL}/api/v1/bungee/status?requestHash=${requestHash}`
    );
    const data = await response.json();

    if (!data.success) {
      const serverReqId = response.headers.get("server-req-id");
      throw new Error(
        `Status error: ${data.statusCode}: ${data.message}. server-req-id: ${serverReqId}`
      );
    }

    // It returns an array since we can have multiple requests in one requestHash
    return data.result[0];
  } catch (error) {
    console.error("Failed to check status:", error);
    throw error;
  }
}

Status Code Enum

Bungee uses the following enum to represent the status of a request. These status codes are returned in the bungeeStatusCode field of the status response:

export enum RequestStatusEnum {
  PENDING = 0,
  ASSIGNED = 1,
  EXTRACTED = 2,
  FULFILLED = 3,
  SETTLED = 4,
  EXPIRED = 5,
  CANCELLED = 6,
  REFUND_PENDING = 7,
  REFUNDED = 8,
}

Status Code Descriptions

PENDING (0)

The request has been submitted to the Bungee Auto system but has not yet been picked up by a solver. This is the initial state of all requests.

ASSIGNED (1)

A solver has been assigned to the request and is working on it. The solver is preparing to execute the request.

EXTRACTED (2)

The solver has extracted the funds from the source chain and is in the process of executing the request.

FULFILLED (3)

The request has been successfully executed on the destination chain. The funds have been delivered to the recipient address.

SETTLED (4)

The request has been fully settled, meaning all operations have been completed and confirmed on both chains.

EXPIRED (5)

The request has expired because it was not processed within the specified time limit. This could happen if no solver was available or if there were network issues.

CANCELLED (6)

The request was cancelled, either by the user or by the system.

REFUND_PENDING (7)

A refund has been initiated for the request, but it has not yet been processed. This typically happens when a request cannot be fulfilled.

REFUNDED (8)

The refund has been processed and the funds have been returned to the user's address on the source chain.

Example Implementation with Polling

Here's an example of how to poll for status updates until a transaction is complete:

// For Auto routes (using requestHash from submission)
let status;
do {
  await new Promise((resolve) => setTimeout(resolve, 5000)); // Wait 5 seconds between checks
  console.log("Checking status...");
  try {
    status = await checkStatus(submitResult.requestHash);
    console.log("Status details:", status.bungeeStatusCode);
  } catch (error) {
    console.error("Failed to check status:", error?.message || "Unknown error");
  }
} while (status?.bungeeStatusCode !== 3); // 3 = FULFILLED

console.log(
  "Transaction complete:",
  "\n- Hash:",
  status.destinationData?.txHash || "Transaction hash not available"
);

// For Manual routes (using transaction hash)
let status;
do {
  await new Promise((resolve) => setTimeout(resolve, 5000)); // Wait 5 seconds between checks
  console.log("Checking status...");
  try {
    status = await checkStatus(transactionHash);
    console.log("Status details:", status?.bungeeStatusCode || "Pending");
  } catch (error) {
    console.error("Failed to check status:", error?.message || "Unknown error");
  }
} while (!status || status?.bungeeStatusCode !== 3); // 3 = FULFILLED

if (status && status.bungeeStatusCode === 3) {
  console.log(
    "Transaction complete:",
    "\n- Hash:",
    status.destinationData?.txHash || "Transaction hash not available"
  );
}