A keychain-sized Fren Pet viewer: what it would take

Research date: 2026-09-27. Everything about Fren Pet's API, contracts and client code was observed live on that date. None of it is a documented, stable interface.

How to read this report

Each claim carries one of these labels:

Tag	Meaning
[F-doc]	Fact from a primary published source (official docs, vendor spec page). The link follows the claim.
[F-obs]	Fact I observed directly: a live API response, an on-chain call, or the shipped pet.game JavaScript/CSS. The method is given so it can be reproduced.
[F-2nd]	Fact from a secondary source (press, wiki, forum). Treat with more caution.
[I]	My inference or engineering judgement. It is not verified.
[?]	Unknown or uncertain.

---

1. Short answer

1. You don't have to build it from scratch. Off-the-shelf ESP32 boards with a small screen and Wi-Fi already exist at keychain size, and they cost roughly $10–$25. Examples are the M5Stack AtomS3 (24 × 24 mm) and M5StickC Plus2 (48 × 24 mm, with battery, RTC and buzzer), and the Waveshare 1.28″ round board. They can fetch pet data over Wi-Fi when you ask them to, then render the pet locally from a clock. The remaining hardware work is mostly an enclosure and a battery choice. [F-doc] for specs (§4), [I] for fitness.
2. Commercial Tamagotchis can't realistically be repurposed. The original P1 runs from mask ROM. The Tamagotchi Uni has an ESP32 Wi-Fi module, but its firmware is closed and I found no public custom-firmware route (§4.3).
3. Fren Pet's data model suits an offline device well. The game is on the Base chain. Each pet has 3-number on-chain DNA that never changes, plus a birth timestamp and an absolute starvation timestamp. With those three values the device can compute appearance, growth stage and the "time until death" countdown from its own clock alone. One fetch per feeding (at most every ~3 days) is enough to keep the countdown correct (§2, §3).
4. The main open questions are not about hardware. They are about permission to use the artwork, the stability of undocumented APIs, the exact rules behind "hungry/starving/dying", and the product scope (§6).

---

2. What Fren Pet is, and which data identifies a pet

2.1 Game facts (documentation)

• Fren Pet is an idle pet game on Base, an Ethereum L2. You feed, train and battle pets. [F-doc] docs.frenpet.xyz
• The game runs at pet.game. The page title is "Fren Pet", and the web-app manifest says "name": "FrenPet". [F-obs] (fetched https://www.pet.game/ and /manifest.json)
• Feeding resets the pet's Time of Death (TOD) to 3 days. A pet that isn't fed goes into a 7-day hibernation. [F-doc] Gameplay
• Pets "start as an EGG and advance to its full reveal as the time passes". Each pet has "onchain DNA composed of 3 parameters: legs, head and ears, it is randomly decided on mint and can't be changed". [F-doc] V2 blog, 9 Nov 2023
• The V2 contracts on Base use a Diamond (EIP-2535) at 0x0e22b5f3e11944578b37ed04f5312dfc246f443c. The pet NFT is at 0x5b51Cf49Cb48617084eF35e7c7d7A21914769ff1. [F-doc] Contracts
• Outdated documentation: the V2 blog names api.frenpet.xyz/graphql as the public API. On 2026-09-27 that hostname served a TLS certificate for *.cloudwaysapps.com (a hostname mismatch), so the documented endpoint is effectively dead. [F-obs] (curl -v)

2.2 What the live system actually exposes (observed)

• GraphQL indexer: the pet.game client uses https://api.pet.game. It accepts unauthenticated POSTs and allows introspection. The pet(id) type includes these fields:

  • dna (string, e.g. "12-0-3")
  • createdAt
  • timeUntilStarving
  • status
  • level, score
  • attackPoints, defensePoints
  • shieldExpires
  • owner, name

  _meta showed the indexer at Base block 51,847,700, roughly 5 seconds behind wall-clock time. [F-obs]

• timeUntilStarving is an absolute Unix timestamp, not a duration. Pet #18594 returned 1790640851, which is about 43 hours after the time of the query. Pet #84052, minted on the day of the query, had timeUntilStarving − createdAt = 259,200 s, exactly 3 days. That matches the documented TOD. [F-obs]

• On-chain fallback: a plain eth_call to the Diamond over the public RPC https://mainnet.base.org works without an API key:

  • getStatus(uint256) (selector 0x5c622a0e) returned 0 ("happy") for the sampled pets.
  • getInfos(uint256) (selector 0x46c27e8c) returned the same timeUntilStarving and birth time as the indexer.

  [F-obs] I did not fully decode the getInfos struct, so I haven't confirmed where the DNA sits in it. [?]

• Accessories come from a different endpoint, https://www.pet.game/api/equip/<id>. It returns hat/mask/glasses item ids. Some pets also have an AI-generated hat, which is a PNG hosted on Vercel Blob with its own position and size. [F-obs]

2.3 How the web client turns data into a picture

Everything below comes from the shipped pet.game JS/CSS bundles, downloaded 2026-09-27. [F-obs]

• Status codes: ["happy","hungry","starving","dying","dead","hibernating","training"], indexed 0–6.

• DNA index 0 selects the sprite family:

  • < 6 → the original "ogpet" layered sprite, where index 0 also selects the ears layer.
  • 6..13 → cat, sheep, pepe, penguin, dragon, monkey, panda, dog.

• DNA index 1 selects the head sprite and index 2 the legs. So the documented "legs, head, ears" list is not in index order. The client uses [ears/species, head, legs].

• Growth stage = floor((now − birth) / 86400) days. Days 0–4 map to stages A–E (child/toddler, with parts appearing progressively). Day 5 and later is stage F (adult). This is pure clock math.

• "Needs hibernation" is shown when timeUntilStarving ≤ now and the pet isn't already hibernating (status 5). The client also defines a constant of 604,800 s (7 days) that it adds to timeUntilStarving as the revival deadline.

• Sprites are small pixel art:

  • Newer species are 32 px-tall strips. panda.png is 704 × 32, about 22 frames of 32 × 32 in 2–3 colours.
  • The layered "ogpet" parts are 246 × 96 two-frame strips of about 1–2 KB each.

  [F-obs] (PNG headers read, and images viewed)

What this means for a device [I]: you need about 40 bytes of static identity (id, DNA triple, birth timestamp) plus one changing timestamp (timeUntilStarving). From those you can compute species, parts, growth stage, the countdown and the revival deadline locally. The pixel art already matches tiny low-colour screens: 32 × 32 frames scaled 3–4× fill a 128 × 128 display. A full sprite set is probably a few hundred KB, which fits easily in the 8–16 MB flash of the boards in §4.

tools/fetch-pet.mjs in this repo reproduces all of this. It prints the compact "pet card" (433–548 bytes as minified JSON for the pets tested) that a device would store.

---

3. What can be computed locally, and what goes stale

Readout	Local from clock + stored data?	Notes
Species / parts / colours	Yes, forever	DNA is immutable on mint [F-doc]
Growth stage (egg → adult)	Yes	days since birth, capped at 5 [F-obs]
"Time until starving" countdown	Yes, until the owner feeds	Feeding moves the timestamp 3 days forward [F-doc]. Stale data only makes the countdown pessimistic, never wrong in the dangerous direction [I]
"Needs hibernation / revive by"	Yes	timeUntilStarving and +7 d [F-obs]
happy / hungry / starving / dying	Partly	The contract computes these. I did not find the time thresholds in client code [?]. You could approximate by time left, but it might disagree with the game
Training, shield, attacks, score, level, ATK/DEF	No	These change with gameplay and other players' attacks. Show them as "as of last sync"
Accessories / AI hat	Snapshot only	The AI hat is a remote PNG that needs downloading and scaling [F-obs]
Death / burn / transfer	No	Only a refresh can detect these

Recommended model [I]:

• Store {id, dna, bornAt, timeUntilStarving, shieldExpires, accessories, fetchedAt}.
• Render entirely from an RTC.
• Show a "last synced X h ago" badge.
• Sync on a button press, or at most around daily.

Sync paths, in rough order of simplicity:

1. Wi-Fi → api.pet.game.
2. Wi-Fi → Base public RPC. This is more durable because it depends only on the chain.
3. Phone → BLE push, where a phone app or web page does the fetch.
4. Manual entry of the DNA triple plus birth date. This covers appearance and growth stage only. The countdown would need the last feeding time typed in too, which is awkward on 1–3 buttons.

---

4. Existing hardware options

4.1 Ready-made ESP32 boards, keychain size or close to it

Device	Size	Screen	Radio	Battery / RTC	Source
M5Stack AtomS3	24 × 24 × 12.9 mm, 6.9 g	0.85″ IPS 128 × 128	Wi-Fi, BLE (ESP32-S3)	No battery, USB-C only	docs.m5stack.com [F-doc]
M5Stack StickC Plus2	48 × 24 × 13.5 mm	1.14″ TFT 135 × 240	Wi-Fi (ESP32-PICO-V3-02, 8 MB flash/2 MB PSRAM)	200 mAh battery, BM8563 RTC, 3 buttons, buzzer, IMU	docs.m5stack.com [F-doc]
Waveshare ESP32-S3-LCD-1.28	~9 g board	1.28″ round IPS 240 × 240	Wi-Fi + BLE 5	LiPo charge header, IMU; $15.99	waveshare.com [F-doc]
LilyGO T-Display-S3	larger (stick)	1.9″ 170 × 320	Wi-Fi + BLE 5	JST battery connector; listed at $9.04 (sold out when checked)	lilygo.cc [F-doc]
SQFMI Watchy	wristwatch	200 × 200 e-paper	ESP32-S3 Wi-Fi/BLE	Open-source hardware (OSHWA), Arduino/MicroPython	watchy.sqfmi.com [F-doc]

Assessment [I]:

• The M5StickC Plus2 is the closest to "flash it and it works". It already has a battery, a real-time clock, buttons and a buzzer, which is everything a Tamagotchi needs. At 48 mm it is keychain-ish rather than egg-sized.
• The AtomS3 has the right size but needs a battery added.
• The round Waveshare board gives the most "toy-like" look inside a custom 3D-printed shell.
• An e-paper device (Watchy-class) gives weeks of battery life and suits a mostly static pet, at the cost of animation.

4.2 Other programmable pocket devices

• Arduboy Mini: about 50 × 35 mm and keychain-sized, with a 128 × 64 mono OLED and a 16 MHz ATmega32u4. It has no radio, so pet data could only be entered by hand or at flash time. It is also powered over USB-C from an external battery, according to press coverage. [F-2nd] Hackaday, Electronics-Lab
• Flipper Zero: 128 × 64 mono screen, BLE but no Wi-Fi, 100 × 40 × 26 mm. It's too big for a keychain but workable as a prototyping target with phone-over-BLE sync. [F-doc] docs.flipper.net
• Pebble (Core Devices): PebbleOS is now 100% open source. Pebble Time 2 shipping was about 80% fulfilled in July 2026, and Round 2 was targeted to ship by the end of September 2026. Apps can use the phone for network access. It's a wrist device, not a keychain. [F-doc] repebble.com, July 2026 · [F-2nd] gadgetsandwearables

4.3 Real Tamagotchi hardware

• Original P1 (1996): it can be emulated. ArduinoGotchi runs the TamaLib emulator on an Arduino Uno with a 128 × 64 SSD1306 OLED, 3 buttons and a buzzer, but you have to supply the copyrighted ROM yourself. That shows a 3-button, 128 × 64 layout is enough for a virtual pet, but emulation doesn't help render Fren Pets. [F-doc] github.com/GaryZ88/ArduinoGotchi
• Tamagotchi Uni: community sources report that its Wi-Fi module is an ESP32, and that reverse-engineering so far covers network traffic, not custom firmware. [F-2nd] Tamagotchi Wiki FAQ, GBAtemp thread. [?] I found no public way to run custom code on it. [I] Treat it as not viable.
• Cheap "virtual pet keychain" clones: in my experience these use one-time-programmable or mask-ROM MCUs with segment or tiny dot-matrix screens. [I], not source-verified. Swapping the board inside the shell is possible, but that is effectively a custom build.

4.4 Build-from-scratch path, if a true egg-sized device is wanted [I]

Parts: an ESP32-C3/S3 module, a 0.96–1.3″ OLED or a 1.54″ e-paper panel, a 100–300 mAh LiPo, a charger IC, 3 buttons, a piezo buzzer, and a custom PCB in a 3D-printed or injection-moulded shell. The ESP32-S3 has an RTC in its low-power domain, but a dedicated RTC chip (as on the StickC Plus2) keeps better time during deep sleep. This is a normal hobbyist project. The risk is in battery life, drift and enclosure, not feasibility.

---

5. Suggested minimal build [I]

1. Hardware: M5StickC Plus2 (no soldering) or a round ESP32-S3 board in a printed shell.
2. Firmware: Arduino/ESP-IDF with LVGL or TFT_eSPI. Store the sprite sheets in flash as indexed-colour arrays.
3. Pairing: a first-boot captive portal (phone connects to the device's Wi-Fi) where the user enters a pet id, or an owner address so the device can list the owner's pets via the observed pets(where:{owner}) query. Wi-Fi credentials are entered in the same step.
4. Sync: button-triggered, or once a day if on Wi-Fi. Use api.pet.game GraphQL, falling back to Base RPC getInfos/getStatus, then deep sleep.
5. Offline logic:
   • stage = f(now − bornAt)
   • countdown = timeUntilStarving − now
   • "revive by" = timeUntilStarving + 7 d
   • buzzer alert at, say, 12 h remaining
   • "stale" badge after 24 h without sync
6. Manual fallback: enter the DNA triple and birth date on the buttons. This gives an appearance-only mode.

---

6. Questions still to answer

Permission and legal

1. Are you allowed to reproduce Fren Pet artwork on a device, especially one that is sold? The docs link brand assets but state no licence terms. [F-doc] Branding. pet.game/terms and /tos returned 404. [F-obs] You would need explicit permission from the team.
2. Would the team sanction or officially support a hardware companion, for example a stable public endpoint or a sprite pack?

Data and API

3. How stable is api.pet.game? It's undocumented, and the documented api.frenpet.xyz is already dead. Could the game migrate chains or contracts? The chain-RPC fallback reduces but doesn't remove this risk.
4. What exact on-chain rules produce hungry → starving → dying? These are needed if the device should show those moods offline. [?]
5. What is the exact layout of the getInfos struct, including where the DNA sits, if you want to depend only on the chain? [?] (partly probed)
6. How should accessories be handled: item-id sprites (hat/mask/glasses) and AI-generated hats (arbitrary remote PNGs)? Options are downloading and dithering them, ignoring them, or asking the team for a small-size variant.
7. Are the species list (ids 6–13) and the "ogpet" part counts final, or will new species appear? New species would need firmware or sprite updates over the air.

Product and UX

8. Is the device view-only, or should it trigger actions such as feeding? Actions need a wallet signature. That brings in key storage on the device, or a phone round-trip, plus security review, which is a much larger scope. [I]
9. How do you identify the pet: pet id, wallet address (multiple pets), or QR code/NFC tap from the phone? Should you support one pet or several?
10. What screen type do you want? Colour LCD gives animation but lasts about 1–2 days on 200 mAh when awake. E-paper gives weeks but little animation. What battery life target? [I], not measured.
11. How much clock drift is acceptable? Without an RTC chip or occasional NTP sync, drift makes the countdown less accurate.
12. How big is the full sprite asset set and what licence covers it? I sampled only a few files.
13. If it's sold as a product: FCC/CE (a pre-certified module helps), battery shipping rules, and the unit cost of the enclosure. [I]

---

7. Method and limits

• What I checked directly:

  • live GraphQL introspection and queries against api.pet.game
  • eth_call against Base mainnet
  • the downloaded pet.game JS/CSS bundles and sample sprite PNGs
  • the /api/equip endpoint

  All on 2026-09-27. Pet ids sampled: 0, 15770, 18594, 84052.

• Not done:

  • no hardware was built or measured, so battery and drift figures are estimates
  • the getInfos struct was not fully decoded
  • I didn't extract mood thresholds
  • I didn't contact the Fren Pet team about licensing
  • vendor prices and stock change often

• Sources: product and spec claims come from vendor or official pages where possible. The Tamagotchi Uni and Arduboy Mini details are from secondary or community sources, and are labelled that way.

• No independent review: this report was produced and checked by a single agent. A structural pass means the file exists in scope. It does not certify that the research is correct.