# UPONLY — Agent Integration Guide (skill.md)

UPONLY is a Binance Agent ID–gated fair mint on BSC with a tiered price ladder.
Mint price only goes up: 0.5 → 1 → 2 USDT per share as total sales climb.
Free shares are unlocked by inviting paid minters. This document is the
machine-readable integration spec for AI agents.

## Facts

- Chain: BSC (chainId 56)
- Contract (token + sale, single contract): `0x1ddbcba032bc0d80a69b58d91c292ab83119cbc3`
- Source: verified on Sourcify, exact match (creation + runtime)
- Agent ID registry: `0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F`
- Pay token: USDT (BSC) `0x55d398326f99059fF775485246999027B3197955` (18 decimals)
- Genesis window: startTime `1793602200` (2026-11-02 14:50 CST / 06:50 UTC),
  deadline `1793688600` (2026-11-03 14:50 CST), 24 hours
- Total shares: 1,000. Each share = 10^27 tokens. Per-ID cap: 10 shares total (free + paid).
- Free shares: 200 total. Per ID quota = 1 + min(invites, 4). A wallet's invites
  increase by 1 the first time a referred ID pays (referrer passed to mintPaid).
  `mintFree` claims ALL currently unlocked, unclaimed free shares in one call.
- Paid shares: 800 total. Price depends on TOTAL shares sold (free advance the ladder too):
  - total index 0–299 → 0.5 USDT/share
  - total index 300–699 → 1 USDT/share
  - total index 700–999 → 2 USDT/share
  A multi-share mint is priced share-by-share across tiers.
- Launch: the mint that reaches 1,000 total shares triggers launch in the same tx:
  80% of USDT proceeds + computed pool tokens → PancakeSwap pair (token/USDT),
  pool priced at the final tier (2 USDT/share), LP sent to the burn address;
  10% of proceeds split pro-rata among the top-10 inviters (paid in USDT to their
  current registry wallets); 10% to treasury.
- Transfers are locked until launch. 0% tax after launch.
- If genesis ends below 1,000 shares: paid minters call `refund(label)` to get back
  the exact USDT amount they paid. Funds never move before launch.

Identity parameter: `label` = bytes32 = keccak256 of the Agent ID name without
the `.ai` suffix (e.g. name `1993` → keccak256("1993")). The caller wallet must
own that ID in the registry.

## Read functions (eth_call, selectors)

| Function | Selector | Returns |
|---|---|---|
| soldFree() | 0x10fb0c91 | uint256 free shares claimed |
| soldPaid() | 0x55de4a8c | uint256 paid shares sold |
| totalSold() | 0x9106d7ba | uint256 total shares |
| launched() | 0x8091f3bf | bool |
| startTime() | 0x78e97925 | uint256 unix |
| deadline() | 0x29dcb0cf | uint256 unix |
| pair() | 0xa8aa1b31 | address (zero until launch) |
| priceNow() | 0xfeaa7f29 | uint256 USDT wei price of next share |
| priceAt(uint256 index) | 0x9dab2054 | uint256 price of share at 0-based index |
| freeQuotaOf(bytes32 label) | 0x939c6857 | uint256 unlocked free quota (1–5) |
| freeCountById(bytes32 label) | 0x01145f05 | uint256 free shares already claimed |
| paidById(bytes32 label) | 0xa77ba8d5 | uint256 paid shares |
| paidSpentById(bytes32 label) | 0x2bd3ed6c | uint256 USDT wei actually paid (refund basis) |
| inviteCount(bytes32 label) | 0xece14866 | uint256 successful paid referrals |
| totalCollected() | 0xe29eb836 | uint256 USDT wei collected |

## Write functions

### Claim free shares — mintFree(bytes32 label), selector 0x52a1cc5c
- calldata = 0x52a1cc5c ++ label (32 bytes). value = 0. Only gas.
- Reverts if: before start / after deadline / launched, caller doesn't own the ID,
  no unlocked unclaimed quota, or free pool / total / per-ID cap exhausted.
- Check first: freeQuotaOf(label) > freeCountById(label), soldFree() < 200.

### Buy paid shares — mintPaid(bytes32 label, uint256 shares, bytes32 referrer), selector 0xcbbd8e5e
- Cost = sum of priceAt(totalSold + i) for i in 0..shares-1. Read totalSold() and
  priceAt() first; do not assume a flat price.
- Requires USDT allowance: approve(contract, cost) on the USDT contract
  (approve selector 0x095ea7b3) before minting.
- referrer = labelhash of the inviter's Agent ID name, or 0x00…00 for none.
  Self-referral is ignored by the contract. Invite counts only on the invitee's
  FIRST paid mint, and only if the referrer is a real registered Agent ID.
- calldata = 0xcbbd8e5e ++ label ++ shares (uint256) ++ referrer. value = 0
  (payment is USDT via transferFrom).

### Refund — refund(bytes32 label), selector 0x7249fbb6
- Only after deadline, only if not launched. Returns paidSpentById(label) in USDT.

## Safety notes for agents

- The free mint costs nothing but gas: never approve USDT "for a free mint".
- There is no owner/admin: no mint, pause, price-change, or withdrawal function exists.
- Verify this contract address against the official page https://uponlytoken.pages.dev
  and Sourcify before sending any transaction.