Skip to main content
Use this endpoint to submit an Ethereum wallet address for gas sponsorship on Arc Network. ArcPass validates eligibility, applies rate limiting, and creates a sponsorship request that moves through the approval and relay pipeline asynchronously. The request captures the submitting IP address and user-agent automatically from the incoming HTTP request. You do not need to include them in the body.

​
Request

POST /sponsorship/request
​
walletAddress
string
required
The Ethereum address to sponsor. Must match ^0x[0-9a-fA-F]{40}$ and be at most 42 characters. The address is normalized to lowercase before processing.

​
Response

​
id
string
required
UUID of the newly created sponsorship request. Use this to poll status with GET /sponsorship/:id.
​
walletId
string
required
UUID of the wallet record associated with this sponsorship request.
​
walletAddress
string
required
The Ethereum address submitted for sponsorship, normalized to lowercase.
​
status
string
required
Initial status of the sponsorship request. Always "pending" on creation.
​
requestedAt
string
required
ISO 8601 timestamp of when the sponsorship request was created.
​
ipAddress
string
required
IP address of the client that submitted the request, captured from X-Forwarded-For or the raw socket address.
​
userAgent
string
required
User-Agent header value from the request, or null if not present.

​
Errors

StatusCause
400walletAddress is missing or does not match the required hex pattern.
409A pending sponsorship request already exists for this wallet.
422The wallet is blocked or has already received a sponsorship.
429Rate limit exceeded for this wallet or IP address.
Replay protection: If the same walletAddress and IP address submit an identical request within 5 seconds, ArcPass returns the existing request rather than creating a duplicate.
curl --request POST \
  --url https://api.arcpass.io/sponsorship/request \
  --header "Content-Type: application/json" \
  --data '{"walletAddress": "0xAbC1234567890dEF1234567890aBcDeF12345678"}'
201
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "walletId": "3f2a1c8e-9b4d-4e7f-a1d2-0c6f8e3b5a9d",
  "walletAddress": "0xabc1234567890def1234567890abcdef12345678",
  "status": "pending",
  "requestedAt": "2025-05-11T10:30:00.000Z",
  "ipAddress": "203.0.113.42",
  "userAgent": "Mozilla/5.0 (compatible; ArcApp/1.0)"
}