Skip to main content

​
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: pharosTestnet, // Chain ID: 688689
  transport: http('<PHAROS_RPC_URL>')
})

// 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 testnet addresses.

​
Network Configuration

ParameterValue
NetworkPharos Atlantic Testnet
Chain ID688689
Block Exploreratlantic.pharosscan.xyz

​
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 Pharos (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