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

# Hooks

> Programmable behavior modules that let your Gotchipus act on-chain

## What Are Hooks?

Hooks are **smart contract modules** that you attach to your Gotchipus to give it autonomous behavior. When specific on-chain events occur, Hooks trigger and execute logic — without requiring your manual intervention.

Think of Hooks as your Gotchipus's **instincts**: pre-programmed responses to the world around it.

## Hook Events

Hooks are triggered at two points in the execution lifecycle:

| Event             | When It Fires                                      | Use Case                                  |
| ----------------- | -------------------------------------------------- | ----------------------------------------- |
| **BeforeExecute** | Before your Gotchipus's TBA executes a transaction | Validation, pre-conditions, guards        |
| **AfterExecute**  | After a transaction completes successfully         | Rewards, state updates, follow-up actions |

Each Gotchipus can have up to **10 Hooks per event**, creating layered behavioral logic.

## How Hooks Work

```
1. An action triggers execution on your Gotchipus's Token-Bound Account
2. BeforeExecute Hooks fire — they can validate, modify, or block the action
3. The transaction executes
4. AfterExecute Hooks fire — they can distribute rewards, log events, or trigger follow-up actions
```

### Hook Parameters

Every Hook receives context about the execution:

| Parameter  | Description                    |
| ---------- | ------------------------------ |
| `tokenId`  | Which Gotchipus is acting      |
| `account`  | The Gotchipus's TBA address    |
| `caller`   | Who initiated the action       |
| `target`   | The contract being called      |
| `value`    | ETH value being sent           |
| `selector` | Which function is being called |

AfterExecute Hooks also receive the execution result (success/failure and return data).

## Managing Hooks

### Adding a Hook

Hooks are added via `addHook(tokenId, hookAddress)` — you attach a deployed smart contract to your Gotchipus. The Hook contract declares which events it supports (BeforeExecute, AfterExecute, or both).

### Removing a Hook

Hooks can be removed at any time by the Gotchipus owner via `removeHook()`.

### Viewing Hooks

Query `getHooks(tokenId, eventType)` to see all Hooks currently attached to a Gotchipus for a specific event.

## Example Hooks

The protocol includes example Hook contracts to demonstrate the pattern:

| Hook              | What It Does                                                 |
| ----------------- | ------------------------------------------------------------ |
| **RewardHook**    | Distributes rewards after successful executions              |
| **WhitelistHook** | Only allows execution against whitelisted contract addresses |

## Building Your Own

Hooks extend the `BaseHook` abstract contract. To create a custom Hook:

1. Inherit from `BaseHook`
2. Implement `beforeExecute()` and/or `afterExecute()`
3. Declare supported events via hook permissions
4. Deploy and attach to your Gotchipus

<Tip>
  For a full development guide, see [Build a Hook](/developers/build-a-hook).
</Tip>

## Why Hooks Matter

Hooks transform Gotchipus from a collectible into a **programmable agent**:

* **For players**: Automate care routines, react to market conditions, optimize strategies
* **For developers**: Build and share behavioral modules, creating an ecosystem of composable AI logic
* **For the ecosystem**: 20,000 Gotchipus running diverse Hook logic creates emergent, unpredictable on-chain behavior — the foundation of an autonomous agent civilization