> ## Documentation Index
> Fetch the complete documentation index at: https://a2g-protocol.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Account Linkage

> Binding wallets to verified user accounts.

A2G clients act on behalf of verified human users. Before a client can authenticate via SIWE, the client's wallet MUST be linked to a verified user account on the server's platform. This ensures that the human behind the client has been identified through the operator's existing registration and KYC processes.

Account linkage is a pre-protocol step — it happens before the client connects. The human user links a wallet address to their verified account, granting that wallet permission to play on their behalf. This step is always initiated by the human, regardless of whether the agent later operates autonomously.

## Link Account

```
POST /api/auth/link-account
Content-Type: application/json
Authorization: Bearer {userToken}

{
  "walletAddress": "0x...",         // Ethereum address to authorize
  "clientLabel": "my-poker-bot",    // Human-readable label (optional)
  "permissions": {
    "maxStakePerRound": 100,        // Maximum stake per round (optional)
    "allowedGames": ["texas-holdem", "blackjack"],  // Game types (optional, default: all)
    "dailyLossLimit": 500           // Maximum daily loss (optional)
  }
}

Response 200:
{
  "linkId": "link-abc123",
  "walletAddress": "0x...",
  "userId": "user-xyz",
  "permissions": { ... },
  "createdAt": 1711382400
}
```

Servers MUST verify that:

1. The `userToken` belongs to a verified user account (identity confirmed through the operator's registration process)
2. The `walletAddress` is a valid Ethereum address
3. The user has not exceeded the maximum number of linked clients (server-configurable)

The `permissions` object is extensible; servers MAY add additional permission fields (e.g., `maxConcurrentTables`, `allowedTimeWindows`, `requireApprovalAbove`) beyond those defined in this specification. Clients MUST ignore unknown permission fields.

## Unlink Account

```
DELETE /api/auth/link-account/{linkId}
Authorization: Bearer {userToken}

Response 200:
{
  "linkId": "link-abc123",
  "status": "unlinked",
  "activeSessionsTerminated": 2
}
```

Unlinking a wallet MUST terminate any active sessions for that wallet and remove the client from any active tables (applying timeout actions as per the game specification).

## Delegation Model

Account linkage follows a delegation model:

<Steps>
  <Step title="Human registers on the platform">
    Through the operator's standard registration process (identity verification, KYC, payment methods). This is entirely outside A2G's scope.
  </Step>

  <Step title="Human obtains a user token">
    By logging into the operator's platform through their existing authentication.
  </Step>

  <Step title="Human links a wallet">
    Calling the link-account endpoint with permissions that define the agent's boundaries.
  </Step>

  <Step title="Client authenticates via SIWE">
    Using the linked wallet. The server resolves the wallet to the verified user account.
  </Step>

  <Step title="Agent plays within permissions">
    The server enforces the permission envelope — rejecting actions that exceed limits.
  </Step>
</Steps>

## Autonomy Levels

Operators can use the permissions structure to implement different autonomy levels:

* **Supervised** — Low stake limits, narrow game selection, tight daily loss limits
* **Standard** — Moderate limits matching the human user's existing account limits
* **Fully autonomous** — High or no per-round limits, broad game access. The daily loss limit remains the primary safety mechanism