> ## 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 /wallets/register — Register a Wallet

> POST /wallets/register — Register a wallet address with ArcPass. Returns a wallet profile including sponsorship count and blocked status.

Use this endpoint to register an Ethereum wallet address with ArcPass. If the address has never been seen before, a new wallet profile is created and the response returns `201 Created`. If the address is already registered, the existing profile is returned with `200 OK`. This endpoint is idempotent — calling it multiple times for the same address is safe.

## Request

**`POST /wallets/register`**

<ParamField body="walletAddress" type="string" required>
  The Ethereum address to register. Must be a checksummed or lowercase hex address matching the pattern `^0x[0-9a-fA-F]{40}$`. Maximum length is 42 characters.
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  UUID uniquely identifying this wallet record.
</ResponseField>

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

<ResponseField name="firstSeenAt" type="string" required>
  ISO 8601 timestamp of when this wallet was first registered with ArcPass.
</ResponseField>

<ResponseField name="lastSeenAt" type="string" required>
  ISO 8601 timestamp of the most recent interaction with this wallet.
</ResponseField>

<ResponseField name="sponsorshipCount" type="integer" required>
  Total number of sponsorship requests ever submitted for this wallet.
</ResponseField>

<ResponseField name="isBlocked" type="boolean" required>
  Whether this wallet has been flagged and blocked from receiving sponsorships.
</ResponseField>

## Errors

| Status | Cause                                                                                |
| ------ | ------------------------------------------------------------------------------------ |
| `400`  | `walletAddress` is missing or does not match the required hex pattern.               |
| `422`  | Validation error — the request body contains unexpected fields or a malformed value. |

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

<CodeGroup>
  ```json 201 (new wallet) theme={null}
  {
    "id": "3f2a1c8e-9b4d-4e7f-a1d2-0c6f8e3b5a9d",
    "walletAddress": "0xabc1234567890def1234567890abcdef12345678",
    "firstSeenAt": "2025-05-11T10:22:00.000Z",
    "lastSeenAt": "2025-05-11T10:22:00.000Z",
    "sponsorshipCount": 0,
    "isBlocked": false
  }
  ```

  ```json 200 (already registered) theme={null}
  {
    "id": "3f2a1c8e-9b4d-4e7f-a1d2-0c6f8e3b5a9d",
    "walletAddress": "0xabc1234567890def1234567890abcdef12345678",
    "firstSeenAt": "2025-05-10T08:00:00.000Z",
    "lastSeenAt": "2025-05-11T10:22:00.000Z",
    "sponsorshipCount": 1,
    "isBlocked": false
  }
  ```
</CodeGroup>