> ## 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.

# Integration Guide

> Integrate with the Gotchipus protocol from your own applications

## Overview

The Gotchipus protocol is open and permissionless. Any application can read Gotchipus data, query attributes, and — with proper authorization — execute actions on behalf of Gotchipus owners.

## Reading On-Chain Data

All Gotchipus data is accessible through the Diamond proxy contract. Use any Ethereum-compatible library (viem, ethers.js, web3.js) to query:

### Basic Queries

```typescript theme={null}
import { createPublicClient, http } from 'viem'

const client = createPublicClient({
  chain: baseMainnet, // Chain ID: 8453
  transport: http('https://mainnet.base.org')
})

// Get total supply
const supply = await client.readContract({
  address: DIAMOND_ADDRESS,
  abi: gotchipusAbi,
  functionName: 'totalSupply'
})

// Get owner of a Gotchipus
const owner = await client.readContract({
  address: DIAMOND_ADDRESS,
  abi: gotchipusAbi,
  functionName: 'ownerOf',
  args: [tokenId]
})

// Get effective attributes
const attrs = await client.readContract({
  address: DIAMOND_ADDRESS,
  abi: gotchipusAbi,
  functionName: 'getAttributes',
  args: [tokenId]
})
```

### Rich Data

```typescript theme={null}
// Get full token info for an owner
const tokens = await client.readContract({
  address: DIAMOND_ADDRESS,
  abi: gotchipusAbi,
  functionName: 'ownedTokenInfo',
  args: [ownerAddress]
})

// Get TBA address for a Gotchipus
const tbaAddress = await client.readContract({
  address: DIAMOND_ADDRESS,
  abi: gotchipusAbi,
  functionName: 'account',
  args: [tokenId]
})
```

## Building on Hooks

The most powerful integration point is the **Hook system**. By deploying a Hook contract, your application can:

* React to Gotchipus TBA executions
* Add validation logic before transactions
* Distribute rewards after successful actions
* Create composable behavior modules

See [Build a Hook](/developers/build-a-hook) for a complete development guide.

## Wearable Integration

The Wearable Diamond (ERC-1155) is a separate contract. Query wearable balances and metadata independently:

```typescript theme={null}
// Check if a Gotchipus has a specific wearable
const balance = await client.readContract({
  address: WEARABLE_DIAMOND_ADDRESS,
  abi: wearableAbi,
  functionName: 'balanceOf',
  args: [tbaAddress, wearableId]
})
```

## Contract Addresses

See [Deployed Contracts](/architecture/contracts) for current addresses.

## Network Configuration

| Parameter          | Value                                        |
| ------------------ | -------------------------------------------- |
| **Network**        | Base                                         |
| **Chain ID**       | 8453                                         |
| **Block Explorer** | [https://basescan.org](https://basescan.org) |

## Best Practices

1. **Use the Diamond address** for all Gotchipus queries — it routes to the correct facet automatically
2. **Cache TBA addresses** — they are deterministic and don't change
3. **Check token status** — distinguish between Beacon (status 0) and summoned Gotchipus (status 1)
4. **Respect session boundaries** — if executing on behalf of users, use the Session system for proper authorization
5. **Gas optimization** — batch reads using `ownedTokenInfo()` instead of querying tokens individually