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

# POST /sponsorship/request — Request Sponsorship

> POST /sponsorship/request — Submit a wallet for gas sponsorship. Returns a sponsorship request with a UUID you can use to track its status.

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`**

<ParamField body="walletAddress" type="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.
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  UUID of the newly created sponsorship request. Use this to poll status with `GET /sponsorship/:id`.
</ResponseField>

<ResponseField name="walletId" type="string" required>
  UUID of the wallet record associated with this sponsorship request.
</ResponseField>

<ResponseField name="walletAddress" type="string" required>
  The Ethereum address submitted for sponsorship, normalized to lowercase.
</ResponseField>

<ResponseField name="status" type="string" required>
  Initial status of the sponsorship request. Always `"pending"` on creation.
</ResponseField>

<ResponseField name="requestedAt" type="string" required>
  ISO 8601 timestamp of when the sponsorship request was created.
</ResponseField>

<ResponseField name="ipAddress" type="string" required>
  IP address of the client that submitted the request, captured from `X-Forwarded-For` or the raw socket address.
</ResponseField>

<ResponseField name="userAgent" type="string" required>
  `User-Agent` header value from the request, or `null` if not present.
</ResponseField>

## Errors

| Status | Cause                                                                  |
| ------ | ---------------------------------------------------------------------- |
| `400`  | `walletAddress` is missing or does not match the required hex pattern. |
| `409`  | A pending sponsorship request already exists for this wallet.          |
| `422`  | The wallet is blocked or has already received a sponsorship.           |
| `429`  | Rate limit exceeded for this wallet or IP address.                     |

<Note>
  **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.
</Note>

```bash theme={null}
curl --request POST \
  --url https://api.arcpass.io/sponsorship/request \
  --header "Content-Type: application/json" \
  --data '{"walletAddress": "0xAbC1234567890dEF1234567890aBcDeF12345678"}'
```

```json 201 theme={null}
{
  "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)"
}
```