# TempaiTown Create Skill

Use this skill when a human wants help creating and submitting one TempaiTown simple item for sale through the live Tempo developer API.

- Generated: 2026-05-11T09:07:12.902Z
- Public site: https://tempai.town
- API base URL: https://api.tempai.town
- Public skill URL: https://api.tempai.town/create/skill.md

## Current scope

- One simple-item collection at a time.
- One sellable item / one SKU only.
- The live simple-item lane is fixed to 2,000 max mints, the deployed factory timer, a $0.10 first buy target, and a 2% upfront primary fee.
- The backend already knows the deployed Tempo mainnet simple-item factory. Do not invent a factory address or a custom onchain start price.
- If auth, signing, deploy, or broadcast is needed, ask the human for the delegated Tempo access-key bundle first unless they already provided it locally.
- The default path is one shot: authenticate, create, sign, broadcast, and submit unless the human explicitly asks you to stop after prepare.

## Required inputs

- collection title
- one image URL, uploadable file, data URL, or explicit permission to generate the image for them

Everything else is optional. If the human does not provide overrides, let the backend derive the rest from the title and the single image.
If the human says `generate it`, treats that as permission to make the image yourself instead of asking for a separate source file.
When generating item art yourself, prefer using a Gemini API key from AuraWallet if one is already available locally. If Gemini is unavailable, generate a simple local SVG, PNG, or sprite strip yourself instead of blocking the create flow.
Vary the art direction when generating: pick a clear lane that fits the title or joke, such as twitch emote, cursed meme creature, sticker cutout, toy render, clean sprite, or deliberate pixel-art styling.
If the human wants generated sprite art instead of supplying art, default to a Petdex/Codex pet sheet when they need Codex compatibility; otherwise use a short animated sprite strip on a transparent background rather than a single still frame.
For generated sprite art, treat sprite metadata as part of the default create path instead of a separate human override question.
TempaiTown rehosts image inputs during create. Only send `overrides.pixelify = true` if the human explicitly wants pixel-art treatment.

## Codex/Petdex pet import

- A local Codex pet folder lives at `~/.codex/pets/<name>` and should contain `pet.json` plus `spritesheet.webp` or `spritesheet.png`.
- Petdex downloads use the same shape. If the human gives you a Petdex zip, unzip it locally and read `pet.json` plus the spritesheet.
- Do not send `~/.codex/...` paths or zip files to the developer API. Read the spritesheet, upload it or convert it to a data URL, and use that sprite sheet as `image`.
- For Codex/Petdex pets, send standard Codex pet sprite geometry in `overrides.itemSprite`: `format: "codex-pet"`, `columns: 8`, `rows: 9`, `frameWidth: 192`, `frameHeight: 208`, `sheetWidth: 1536`, and `sheetHeight: 1872`.
- Preserve the pet manifest under `itemAttributes.codexPet` when available so the item keeps its original Codex/Petdex identity.

## Default flow

This should be simple enough for a basic agent. Keep the default path to title, image, auth, create, sign, broadcast, and submit.

1. Ask the human for the title and one image first.
2. If the human says `generate it` or otherwise wants generated art, generate the image yourself. Prefer Gemini image generation through an AuraWallet Gemini key when one is already available locally, and otherwise generate a simple local SVG, PNG, or sprite sheet yourself.
3. When you generate the art, choose one strong style direction instead of a bland default. Good lanes include twitch emote, cursed meme, clean mascot sticker, toy-like render, pixel sprite, or other funny internet-native art that matches the prompt.
4. If the human wants you to generate sprite art and needs Codex/Petdex compatibility, use a Petdex/Codex pet sheet (1536x1872, 8x9, 192x208 frames). Otherwise, default to a short four-frame animated sprite strip on a transparent background with width exactly four times the frame height.
5. If you generated a Petdex/Codex sheet or sprite strip yourself, include `overrides.itemSprite` automatically from that layout. Do not ask the human for that metadata as a separate override.
6. After you have both, ask one follow-up only: do they want any overrides. If they say no, do not ask about symbols, descriptions, traits, sprite metadata, or pixelify.
7. If the human gives local files and you can use the signed-in upload route, upload them first with `POST /api/upload`. Otherwise use a reachable URL or a data URL. Never send raw local filesystem paths to the developer API.
8. Do not ask for a wallet on the default path. The backend derives the real creator wallet from the authenticated Tempo bundle.
9. If you need to authenticate, prepare, sign, or broadcast and you do not already have the delegated Tempo access-key bundle locally, ask the human for it first. A `tempo-agent.json` bundle or equivalent wallet/access-key/private-key payload is acceptable.
10. Authenticate the external Tempo agent through https://api.tempai.town/api/tempo/developer/v1/agent-auth/bootstrap by sending the local bundle. Use the lower-level https://api.tempai.town/api/tempo/developer/v1/agent-auth/challenge and https://api.tempai.town/api/tempo/developer/v1/agent-auth/verify routes only if you explicitly need to split the auth flow.
11. Call https://api.tempai.town/api/tempo/developer/v1/simple-items/create with `title`, `image`, and optional `overrides`. The backend derives the creator wallet from the authenticated bundle. The create endpoint already validates the payload and locks the live $0.10 lane for you.
12. Return the pack id, preparation id, asset URLs, and final payload so the human can review it, then continue the same run unless the human asked you to stop after prepare.
13. First try sending the prepared transaction directly with the delegated Tempo access key the human provided.
14. If the direct send fails because the wallet cannot cover Tempo gas or fee-token costs, rebuild the same prepared call as a sponsored Tempo transaction and retry through https://api.tempai.town/api/tempo/developer/v1/fees/sponsor.
15. If https://api.tempai.town/api/tempo/developer/v1/fees/sponsor returns 401, stop and ask the human to create or register the TempaiTown external agent for that wallet and give you the delegated Tempo access-key bundle, then rerun https://api.tempai.town/api/tempo/developer/v1/agent-auth/bootstrap before retrying sponsorship.
16. After either path succeeds, call https://api.tempai.town/api/tempo/developer/v1/simple-items/submit with the resulting tx hash and return the submitted pack status.

## API surface

- Default happy-path endpoints:
  - https://api.tempai.town/api/tempo/developer/v1/agent-auth/bootstrap accepts a local Tempo agent bundle and returns the bearer token in one step.
- Lower-level auth fallback endpoints:
  - https://api.tempai.town/api/tempo/developer/v1/agent-auth/challenge starts external-agent auth.
  - https://api.tempai.town/api/tempo/developer/v1/agent-auth/verify verifies the access-key signature and returns a bearer token.
  - https://api.tempai.town/api/tempo/developer/v1/simple-items/create creates the backend record, validates the payload, and returns the exact Tempo factory create call.
- Optional helper: `POST /api/upload` with multipart form field `file` can upload cover or item art and return a CDN URL if the agent has the user session needed for that route.
- The simple-item backend rehosts image inputs to Cloudflare during prepare.
- The simple-item backend rehosts image inputs to Cloudflare during create and can pixelify them when `pixelify: true` is requested.
- https://api.tempai.town/api/tempo/developer/v1/simple-items/submit binds the broadcast tx hash back to TempaiTown after the create tx is sent, whether it was sent directly or through sponsorship.
- https://api.tempai.town/api/tempo/developer/v1/fees/sponsor is the sponsored relay fallback for authenticated create requests. It is rate-limited per registered agent key.
- A 401 from https://api.tempai.town/api/tempo/developer/v1/fees/sponsor means the agent is missing valid TempaiTown developer auth for that wallet. Ask the human to create or register the external agent and provide the delegated Tempo access-key bundle, then rerun https://api.tempai.town/api/tempo/developer/v1/agent-auth/bootstrap.
- https://api.tempai.town/api/tempo/developer/v1/simple-items/validate is optional for a dry-run validation check. Do not call it on the default path because create already validates.
- https://api.tempai.town/api/tempo/developer/v1/simple-items/:packId, https://api.tempai.town/api/tempo/developer/v1/simple-items/:packId/status, and https://api.tempai.town/api/tempo/developer/v1/simple-items/:packId/metadata/refresh are follow-up endpoints only. Use them when revisiting an existing prepared pack or repairing metadata, not for the first create.

## Broadcast And Submit

- The create endpoint does not broadcast the transaction for you. It returns the exact prepared Tempo write you must send first.
- Use a Tempo-aware client for broadcast. Do not use plain `ethers` raw signing or a plain EVM `eth_sendRawTransaction` flow because the create write needs the Tempo transaction envelope and `feeToken=pathUSD`.
- The prepared response already tells you the critical write fields: `transaction.chainId`, `transaction.feeToken`, `transaction.from`, `transaction.to`, `transaction.data`, `transaction.value`, and `transaction.keyAuthorizationRequired`.
- If the delegated access key has not been bootstrapped onchain yet, use the `keyAuthorization` from `tempo-agent.json` to bootstrap it before the create send. Sponsorship only covers fees for the create tx; it does not replace access-key bootstrap.
- The sponsor relay is not a replacement for create or submit. It only fee-payer-signs the exact prepared Tempo transaction after you authenticate with the TempaiTown bearer token.
- https://api.tempai.town/api/tempo/developer/v1/simple-items/submit does not broadcast. It only verifies that the tx hash already exists on Tempo RPC and matches the prepared create call, then binds that tx hash back to TempaiTown.

### Direct send example

```js
import { createWalletClient, http } from "viem";
import { tempoModerato } from "viem/chains";
import { Account } from "viem/tempo";

const account = Account.fromSecp256k1(bundle.privateKey, {
  access: bundle.wallet,
});

const chain = {
  ...tempoModerato,
  id: 4217,
  name: "Tempo",
  feeToken: bundle.feeToken,
  rpcUrls: {
    default: { http: [bundle.network.rpcUrl] },
    public: { http: [bundle.network.rpcUrl] },
  },
};

const client = createWalletClient({
  account,
  chain,
  transport: http(bundle.network.rpcUrl),
});

const txHash = await client.sendTransaction({
  account,
  to: prepared.transaction.to,
  data: prepared.transaction.data,
  value: BigInt(prepared.transaction.value || "0x0"),
  feeToken: chain.feeToken,
});
```

### Submit example

```bash
curl -X POST "https://api.tempai.town/api/tempo/developer/v1/simple-items/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"packId":"$PACK_ID","preparationId":"$PREPARATION_ID","txHash":"$TX_HASH"}'
```

## Example create payload

```json
{
  "title": "Night Market Posters",
  "image": "data:image/png;base64,..."
}
```

## Minimal payload

- `title` and `image` are the default happy-path fields.
- `image` is enough for the media side of the minimal flow. The backend will reuse it for both the collection cover art and the only sellable item when separate overrides are missing.
- Send optional customization inside `overrides`. Flat legacy fields still work, but `overrides` is the preferred create shape for lower-level agents.

## Optional overrides

- Only ask for overrides if the human says they want them.
- Put optional create customizations inside an `overrides` object when you want the request shape to stay simple for a lower-level agent.
- `featuredImage` is the collection cover art when you want a separate override.
- `itemImage`, `itemName`, and `itemDescription` describe the only sellable item when you want separate overrides.
- `itemSprite` is optional structured sprite metadata for the only sellable item. Only ask the human for it when they supplied the art and the frame layout is unclear.
- If you generated the sprite art yourself and the output is a Petdex/Codex pet sheet or four-frame horizontal strip, include `itemSprite` automatically instead of asking the human for that override.
- If the human wants generated moving sprite art and asks for Codex/Petdex compatibility, use a Petdex/Codex pet sheet (1536x1872, 8x9, 192x208 frames). Otherwise default to a four-frame horizontal strip on a transparent background with width exactly four times the frame height.
- If the human asks you to generate the image, prefer a locally available Gemini key from AuraWallet first. If that is missing, fall back to a simple local SVG, PNG, or sprite generator instead of stopping.
- When generating art yourself, vary the visual language intentionally instead of reusing one default look every time. Pick a lane such as twitch emote, meme, sticker, toy render, or pixel-art sprite based on the prompt.
- `pixelify` is optional. Only send `pixelify: true` when the human explicitly wants pixel-art treatment.
- The backend derives `symbol`, `tokenSymbol`, item name, and default descriptions when you omit them.
- `itemAttributes` is optional when the human wants traits on the only sellable item. For Codex/Petdex pet imports, include `itemAttributes.codexPet` from `pet.json` when available.
- `contentType` is optional. For custom simple-item creates, only use `art`, `game`, or `membership`.
- Optional website, X, or item links are not first-class simple-item fields yet. Keep them in your human-facing notes unless the backend adds dedicated fields.
- The current developer simple-item endpoint persists one item only. Do not send multi-item arrays or rarity ladders.
- The API locks the simple-item launch preset internally. Do not override `startPrice` unless the backend changes.
- Use a reachable URL, uploaded CDN URL, or a data URL for images.

## Guardrails

- Do not guess missing metadata. Ask the human.
- Do not ask about optional overrides until after the human gives you the title and image.
- Do not block on missing source art when the human already told you to generate it. Make the art yourself and keep moving.
- Do not create a generated sprite item from a plain still image. If you promised sprite art, generate or normalize a valid Petdex/Codex pet sheet or four-frame horizontal strip first.
- Do not omit `itemSprite` when you generated a sprite strip yourself. Include the inferred frame metadata automatically.
- Do not send `pixelify` unless the human explicitly asks for pixel-art treatment.
- Do not promise arbitrary launch pricing or mint timing. The live preset is fixed to the currently deployed simple-item lane.
- Do not silently reuse an old preparation or overwrite existing metadata without confirming the pack id.
- Do not assume a delegated Tempo key bundle already exists locally. Ask the human for it before auth/sign/deploy if needed.
- Do not pass `wallet` on the default path. The backend derives the creator wallet from the authenticated bundle.
- Do not call the dry-run validate endpoint on the default path. Create already validates.
- Do not stop at prepare unless the human explicitly asks you to stop there.
- When broadcasting, prefer direct delegate-key submission first. Only fall back to sponsorship for insufficient gas or fee-token failures.
- Do not keep retrying the sponsor relay after a 401. That means you need the human to provision or register the external agent and give you the delegated Tempo access-key bundle first.
- Prefer the bootstrap auth endpoint for simple agents. Only drop to challenge/verify if you need the split flow for debugging.