> ## 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.

# Get Started with ArcPass

> Register your Arc Network wallet and request your first gas sponsorship using the ArcPass REST API. Get tokens delivered to your wallet in under 5 minutes.

ArcPass gives new Arc Network wallets their first gas tokens through a simple three-step API flow. You register your wallet, request a sponsorship, and then poll for status until the tokens arrive. This guide walks through each step with working `curl` examples and real response shapes.

<Note>
  All requests in this guide target the ArcPass REST API. Wallet addresses must be valid 20-byte Ethereum-format hex strings prefixed with `0x` — exactly 42 characters total.
</Note>

<Steps>
  <Step title="Register your wallet">
    Before requesting a sponsorship, you must register your wallet address. Registration creates your wallet record in ArcPass and confirms that your address is correctly formatted.

    **Endpoint:** `POST /wallets/register`

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://api.arcpass.xyz/wallets/register \
        -H "Content-Type: application/json" \
        -d '{"walletAddress": "0x1234567890abcdef1234567890abcdef12345678"}'
      ```
    </CodeGroup>

    **Request body**

    | Field           | Type   | Required | Description                                                          |
    | --------------- | ------ | -------- | -------------------------------------------------------------------- |
    | `walletAddress` | string | Yes      | Your Arc Network wallet address (`0x` followed by 40 hex characters) |

    **Response — new wallet (HTTP 201)**

    ```json theme={null}
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "firstSeenAt": "2026-05-11T10:00:00.000Z",
      "lastSeenAt": "2026-05-11T10:00:00.000Z",
      "sponsorshipCount": 0,
      "isBlocked": false
    }
    ```

    **Response — existing wallet (HTTP 200)**

    If your wallet is already registered, you receive a `200` response with the same shape. The `lastSeenAt` timestamp is updated automatically.

    <Warning>
      If your wallet has been blocked due to prior abuse, the API returns a `403` error. Blocked wallets cannot request sponsorship.
    </Warning>
  </Step>

  <Step title="Request sponsorship">
    Once your wallet is registered, submit a sponsorship request. ArcPass checks your eligibility and, if you qualify, creates a request in `pending` status.

    **Endpoint:** `POST /sponsorship/request`

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://api.arcpass.xyz/sponsorship/request \
        -H "Content-Type: application/json" \
        -d '{"walletAddress": "0x1234567890abcdef1234567890abcdef12345678"}'
      ```
    </CodeGroup>

    **Request body**

    | Field           | Type   | Required | Description                                      |
    | --------------- | ------ | -------- | ------------------------------------------------ |
    | `walletAddress` | string | Yes      | The same wallet address you registered in step 1 |

    **Response (HTTP 201)**

    ```json theme={null}
    {
      "id": "f7e8d9c0-b1a2-3456-cdef-789012345678",
      "walletId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "pending",
      "requestedAt": "2026-05-11T10:00:05.000Z",
      "approvedAt": null,
      "rejectedAt": null,
      "completedAt": null,
      "failedAt": null,
      "ipAddress": "203.0.113.42",
      "userAgent": "curl/8.4.0"
    }
    ```

    Save the `id` field from this response — you will use it in the next step to poll for status.

    <Info>
      ArcPass rejects duplicate requests from the same wallet and IP within a 5-second window. If you receive a `429` error immediately after a previous request, wait a few seconds before retrying.
    </Info>
  </Step>

  <Step title="Poll for sponsorship status">
    After submitting your request, poll the status endpoint using the `id` you received. The request moves through `pending → approved → relayed → completed` as the relay processes it.

    **Endpoint:** `GET /sponsorship/:id`

    <CodeGroup>
      ```bash curl theme={null}
      curl https://api.arcpass.xyz/sponsorship/f7e8d9c0-b1a2-3456-cdef-789012345678
      ```
    </CodeGroup>

    **Response — pending (HTTP 200)**

    ```json theme={null}
    {
      "id": "f7e8d9c0-b1a2-3456-cdef-789012345678",
      "walletId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "pending",
      "requestedAt": "2026-05-11T10:00:05.000Z",
      "approvedAt": null,
      "rejectedAt": null,
      "completedAt": null,
      "failedAt": null,
      "wallet": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
        "sponsorshipCount": 0,
        "isBlocked": false
      },
      "relayTransactions": []
    }
    ```

    **Response — completed (HTTP 200)**

    ```json theme={null}
    {
      "id": "f7e8d9c0-b1a2-3456-cdef-789012345678",
      "walletId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "completed",
      "requestedAt": "2026-05-11T10:00:05.000Z",
      "approvedAt": "2026-05-11T10:00:10.000Z",
      "rejectedAt": null,
      "completedAt": "2026-05-11T10:00:18.000Z",
      "failedAt": null,
      "wallet": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
        "sponsorshipCount": 1,
        "isBlocked": false
      },
      "relayTransactions": [
        {
          "id": "c9d8e7f6-a5b4-3210-9876-fedcba012345",
          "status": "confirmed",
          "relayAttempt": 1,
          "transactionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
          "submittedAt": "2026-05-11T10:00:11.000Z",
          "confirmedAt": "2026-05-11T10:00:17.000Z",
          "failedAt": null,
          "failureReason": null
        }
      ]
    }
    ```

    <Tip>
      Poll every 3–5 seconds. Most sponsorships complete within 30 seconds, but on-chain confirmation time depends on Arc Network block times. Stop polling once `status` is `completed`, `rejected`, or `failed`.
    </Tip>

    **Sponsorship status values**

    | Status      | Meaning                                                        |
    | ----------- | -------------------------------------------------------------- |
    | `pending`   | Queued — the relay has not yet processed your request          |
    | `approved`  | Eligibility confirmed; relay transaction is being prepared     |
    | `relayed`   | On-chain transaction broadcast; waiting for block confirmation |
    | `completed` | Tokens delivered to your wallet                                |
    | `rejected`  | Wallet blocked or ineligible; no further action possible       |
    | `failed`    | On-chain transaction failed; may be retried automatically      |
  </Step>

  <Step title="Check your wallet balance on Arc Network">
    Once your sponsorship reaches `completed` status, native tokens are in your wallet. You can verify your balance using any Arc Network RPC client or block explorer.

    The `transactionHash` field in the `relayTransactions` array contains the on-chain transaction hash. Use it to look up the confirmed transfer on the Arc Network block explorer or to call the SponsorshipRegistry contract's `isSponsored()` view function directly.

    <Check>
      Your wallet now has a non-zero balance and can sign and broadcast transactions on Arc Network independently.
    </Check>
  </Step>
</Steps>

## Next steps

* Read [How ArcPass works](/how-it-works) for a deeper explanation of eligibility checks and the sponsorship lifecycle.
* See the [API reference](/api-reference/overview) for the complete endpoint documentation, including wallet lookup and sponsorship history.
* If you're building an integration, the [request sponsorship guide](/guides/request-sponsorship) covers error handling and edge cases in detail.