> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chipipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# useAddSessionKeyToContract

> Register a session key on the CHIPI wallet smart contract. This one-time operation requires owner signature and enables the session key to execute transactions.

<Info>
  Session keys only work with **CHIPI wallets**. This hook requires the owner's `encryptKey` (PIN) to sign the registration transaction.
</Info>

## Usage

```typescript theme={null}
const { 
  addSessionKeyToContract,
  addSessionKeyToContractAsync, 
  data, 
  isLoading, 
  error,
  isSuccess,
  reset
} = useAddSessionKeyToContract();
```

### Parameters

| Parameter              | Type          | Required | Description                                                         |
| ---------------------- | ------------- | -------- | ------------------------------------------------------------------- |
| `params.encryptKey`    | string        | Yes      | Owner's PIN to decrypt wallet private key for signing               |
| `params.wallet`        | WalletData    | Yes      | Wallet object with `publicKey`, `encryptedPrivateKey`, `walletType` |
| `params.sessionConfig` | SessionConfig | Yes      | Session configuration (see below)                                   |
| `bearerToken`          | string        | Yes      | Authentication token from your auth provider                        |

### SessionConfig Structure

```typescript theme={null}
{
  sessionPublicKey: string;    // From useCreateSessionKey().data.publicKey
  validUntil: number;          // Unix timestamp (seconds)
  maxCalls: number;            // Maximum transactions allowed
  allowedEntrypoints: string[]; // Whitelisted function selectors (empty = all allowed)
}
```

### Return Value

| Property                       | Type          | Description                                         |
| ------------------------------ | ------------- | --------------------------------------------------- |
| `addSessionKeyToContract`      | function      | Trigger registration (fire-and-forget)              |
| `addSessionKeyToContractAsync` | function      | Trigger registration (returns Promise with tx hash) |
| `data`                         | string        | Transaction hash of registration                    |
| `isLoading`                    | boolean       | Whether registration is in progress                 |
| `isError`                      | boolean       | Whether an error occurred                           |
| `error`                        | Error \| null | Error details if any                                |
| `isSuccess`                    | boolean       | Whether registration succeeded                      |
| `reset`                        | function      | Reset mutation state                                |

## Example Implementation

```typescript theme={null}
import { 
  useAddSessionKeyToContract,
  useCreateSessionKey,
  useGetWallet 
} from "@chipi-stack/chipi-react";

export function RegisterSession() {
  const { createSessionKeyAsync } = useCreateSessionKey();
  const { addSessionKeyToContractAsync, isLoading, error } = useAddSessionKeyToContract();
  const { data: wallet } = useGetWallet({ 
    params: { externalUserId: "user-123" },
    getBearerToken 
  });
  
  const [pin, setPin] = useState('');

  const handleRegisterSession = async () => {
    const bearerToken = await getBearerToken();
    
    // Step 1: Create session key
    const session = await createSessionKeyAsync({
      encryptKey: pin,
      durationSeconds: 3600,
    });
    
    // Step 2: Register on contract
    const txHash = await addSessionKeyToContractAsync({
      params: {
        encryptKey: pin,
        wallet: {
          publicKey: wallet.publicKey,
          encryptedPrivateKey: wallet.encryptedPrivateKey,
          walletType: "CHIPI",
        },
        sessionConfig: {
          sessionPublicKey: session.publicKey,
          validUntil: session.validUntil,
          maxCalls: 100,           // Allow 100 transactions
          allowedEntrypoints: [],  // Empty = all functions allowed
        },
      },
      bearerToken,
    });
    
    // Store session for later use
    localStorage.setItem('chipiSession', JSON.stringify(session));
    
    console.log('Session registered:', txHash);
  };

  return (
    <div className="p-6 bg-white rounded-lg shadow">
      <h2 className="text-xl font-semibold mb-4">Register Session Key</h2>
      
      <input
        type="password"
        value={pin}
        onChange={(e) => setPin(e.target.value)}
        placeholder="Enter your PIN"
        className="w-full p-2 border rounded mb-4"
      />
      
      <button
        onClick={handleRegisterSession}
        disabled={isLoading || !pin || !wallet}
        className="w-full bg-blue-600 text-white py-2 rounded hover:bg-blue-700 disabled:bg-gray-400"
      >
        {isLoading ? 'Registering...' : 'Register Session'}
      </button>

      {error && (
        <div className="mt-4 p-3 bg-red-50 text-red-700 rounded">
          Error: {error.message}
        </div>
      )}
    </div>
  );
}
```

## Restricting Session Permissions

For enhanced security, whitelist specific function selectors:

```typescript theme={null}
const txHash = await addSessionKeyToContractAsync({
  params: {
    encryptKey: pin,
    wallet: walletData,
    sessionConfig: {
      sessionPublicKey: session.publicKey,
      validUntil: session.validUntil,
      maxCalls: 10,  // Only 10 calls allowed
      allowedEntrypoints: [
        "0x83afd3f4caedc6eebf44246fe54e38c95e3179a5ec9ea81740eca5b482d12e", // transfer
        "0x219209e083275171774dab1df80982e9df2096516f06319c5c6d71ae0a8480c", // approve
      ],
    },
  },
  bearerToken,
});
```

<Tip>
  Limiting `allowedEntrypoints` restricts what functions the session can call. This is recommended for production to minimize attack surface.
</Tip>

## Error Handling

Common errors:

| Error                                    | Cause                      | Solution                                                   |
| ---------------------------------------- | -------------------------- | ---------------------------------------------------------- |
| `Session keys require CHIPI wallet type` | Wallet is READY type       | Create a new wallet with `walletType: "CHIPI"`             |
| `Invalid encryptKey`                     | Wrong PIN entered          | Verify the PIN matches the one used during wallet creation |
| `Session already exists`                 | Session already registered | Use `useGetSessionData` to check status                    |

<Warning>
  Registration requires a blockchain transaction. The transaction is gas-sponsored but may take 10-30 seconds to confirm.
</Warning>