> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcpass.vibepas.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Track Your Sponsorship Request Status

> Check sponsorship request status by ID, understand each lifecycle state, and look up on-chain relay transaction details using the ArcPass API.

After you submit a sponsorship request, ArcPass processes it asynchronously through a relay worker. You can poll the API at any time to see where your request is in the lifecycle, retrieve the associated relay transaction record, or look up a request by its on-chain transaction hash.

## Check status by request ID

Send a `GET` request to `/sponsorship/:id` using the UUID you received when you created the request.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.arcpass.example/sponsorship/e7f1c2d3-4567-89ab-cdef-012345678901
  ```

  ```json Response (200 OK) theme={null}
  {
    "id": "e7f1c2d3-4567-89ab-cdef-012345678901",
    "walletId": "b3d2c1a0-1234-5678-abcd-ef0123456789",
    "status": "completed",
    "eligibilityReason": null,
    "requestedAt": "2025-05-10T12:00:05.000Z",
    "approvedAt": "2025-05-10T12:00:08.000Z",
    "rejectedAt": null,
    "completedAt": "2025-05-10T12:00:22.000Z",
    "failedAt": null,
    "ipAddress": "203.0.113.42",
    "userAgent": "curl/8.4.0",
    "wallet": {
      "id": "b3d2c1a0-1234-5678-abcd-ef0123456789",
      "walletAddress": "0xa3f2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0",
      "firstSeenAt": "2025-05-10T12:00:00.000Z",
      "lastSeenAt": "2025-05-10T12:00:22.000Z",
      "sponsorshipCount": 1,
      "isBlocked": false
    },
    "relayTransactions": [
      {
        "id": "f9e8d7c6-5432-10ba-9876-543210fedcba",
        "status": "confirmed",
        "relayAttempt": 1,
        "transactionHash": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
        "submittedAt": "2025-05-10T12:00:10.000Z",
        "confirmedAt": "2025-05-10T12:00:22.000Z",
        "failedAt": null,
        "failureReason": null
      }
    ]
  }
  ```
</CodeGroup>

## Sponsorship status lifecycle

| Status      | Meaning                                                                       | What to do                                                   |
| ----------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `pending`   | Request received; waiting for the relay worker to pick it up.                 | Poll again in a few seconds.                                 |
| `approved`  | Relay worker picked up the request and is preparing the on-chain transaction. | Poll again in a few seconds.                                 |
| `relayed`   | Transaction submitted to Arc Network; waiting for confirmation.               | Poll again in a few seconds.                                 |
| `completed` | Transaction confirmed. Gas has been delivered to your wallet.                 | No action needed — you're ready to transact.                 |
| `rejected`  | Wallet is ineligible (already sponsored or blocked).                          | Check `eligibilityReason` for details; no retry is possible. |
| `failed`    | Relay failed after exhausting all retry attempts.                             | Contact support or resubmit after investigating the failure. |

`completed`, `rejected`, and `failed` are terminal states. Once a request reaches one of these statuses it will not change.

<Note>
  The relay worker retries failed relay attempts up to 5 times before marking the request as `failed`. Each attempt is recorded as a separate entry in `relayTransactions`, with `relayAttempt` incrementing from 1.
</Note>

## Check relay transaction details

Each sponsorship request can have one or more relay transaction records. Retrieve a specific relay transaction by its UUID to see low-level details including the on-chain transaction hash, submission time, confirmation time, and any failure reason.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.arcpass.example/relay/f9e8d7c6-5432-10ba-9876-543210fedcba
  ```

  ```json Response (200 OK) theme={null}
  {
    "id": "f9e8d7c6-5432-10ba-9876-543210fedcba",
    "sponsorshipRequestId": "e7f1c2d3-4567-89ab-cdef-012345678901",
    "status": "confirmed",
    "relayAttempt": 1,
    "transactionHash": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
    "submittedAt": "2025-05-10T12:00:10.000Z",
    "confirmedAt": "2025-05-10T12:00:22.000Z",
    "failedAt": null,
    "failureReason": null
  }
  ```
</CodeGroup>

The relay transaction `status` field follows its own lifecycle: `queued` → `submitted` → `confirmed` (or `failed`).

## Look up by transaction hash

If you already have the on-chain transaction hash, you can find the associated sponsorship request directly.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.arcpass.example/sponsorship/tx/0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b"
  ```
</CodeGroup>

The response shape is the same as the relay transaction object above.

## Polling guidance

Poll `/sponsorship/:id` every few seconds until the status reaches a terminal state (`completed`, `rejected`, or `failed`). Most requests complete within 30 seconds under normal network conditions. If the status remains `pending` or `approved` for more than a few minutes, check the [dashboard](/guides/dashboard) for service health.