Integration Guide

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

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

// 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 for a complete development guide.

Wearable Integration

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

// 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 for current addresses.

Network Configuration

Parameter	Value
Network	Base
Chain ID	8453
Block Explorer	https://basescan.org

Best Practices

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

Welcome

Beacon World

Living in Beacon World

The Gotchipus

The Chain Beneath

Architecture

Developers

Vision

Overview

Reading On-Chain Data

Basic Queries

Rich Data

Building on Hooks

Wearable Integration

Contract Addresses

Network Configuration

Best Practices

​Overview

​Reading On-Chain Data

​Basic Queries

​Rich Data

​Building on Hooks

​Wearable Integration

​Contract Addresses

​Network Configuration

​Best Practices

Overview

Reading On-Chain Data

Basic Queries

Rich Data

Building on Hooks

Wearable Integration

Contract Addresses

Network Configuration

Best Practices