Get Started with ArcPass

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.

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.

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

curl -X POST https://api.arcpass.xyz/wallets/register \
  -H "Content-Type: application/json" \
  -d '{"walletAddress": "0x1234567890abcdef1234567890abcdef12345678"}'

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)

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

If your wallet has been blocked due to prior abuse, the API returns a 403 error. Blocked wallets cannot request sponsorship.

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

curl -X POST https://api.arcpass.xyz/sponsorship/request \
  -H "Content-Type: application/json" \
  -d '{"walletAddress": "0x1234567890abcdef1234567890abcdef12345678"}'

Request body

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

Response (HTTP 201)

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

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.

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

curl https://api.arcpass.xyz/sponsorship/f7e8d9c0-b1a2-3456-cdef-789012345678

Response — pending (HTTP 200)

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

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

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.

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

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.

Your wallet now has a non-zero balance and can sign and broadcast transactions on Arc Network independently.

Next steps

Read How ArcPass works for a deeper explanation of eligibility checks and the sponsorship lifecycle.
See the API reference for the complete endpoint documentation, including wallet lookup and sponsorship history.
If you’re building an integration, the request sponsorship guide covers error handling and edge cases in detail.

Get Started

Using ArcPass

Core Concepts

Configuration

FAQ

Get Started with ArcPass

Next steps

​Next steps

Next steps