Skip to main content

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.

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

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
curl -X POST https://api.arcpass.xyz/wallets/register \
  -H "Content-Type: application/json" \
  -d '{"walletAddress": "0x1234567890abcdef1234567890abcdef12345678"}'
Request body
FieldTypeRequiredDescription
walletAddressstringYesYour 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.
2

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
FieldTypeRequiredDescription
walletAddressstringYesThe 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.
3

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
StatusMeaning
pendingQueued — the relay has not yet processed your request
approvedEligibility confirmed; relay transaction is being prepared
relayedOn-chain transaction broadcast; waiting for block confirmation
completedTokens delivered to your wallet
rejectedWallet blocked or ineligible; no further action possible
failedOn-chain transaction failed; may be retried automatically
4

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.