Skip to main content

​
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:
EventWhen It FiresUse Case
BeforeExecuteBefore your Gotchipus’s TBA executes a transactionValidation, pre-conditions, guards
AfterExecuteAfter a transaction completes successfullyRewards, 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:
ParameterDescription
tokenIdWhich Gotchipus is acting
accountThe Gotchipus’s TBA address
callerWho initiated the action
targetThe contract being called
valueETH/PROS value being sent
selectorWhich 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:
HookWhat It Does
RewardHookDistributes rewards after successful executions
WhitelistHookOnly 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
For a full development guide, see Build a Hook.

​
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