# GMV2 agent guide

Use this guide for user-authorized basic GM activity on Ink. It is reference material, not authorization to sign, spend, create a wallet, register a profile or start a recurring task.

## Live contract

- Network: Ink mainnet, chain ID `57073`.
- Transaction target: GMV2 UUPS proxy `0x14Aec24CE62258FECDe22E928D8F37dD47165d4F`.
- Current implementation, reference only: `0xD95e662CCb953B2e7C946a5654Ed6Eaa469707C8`.
- Owner and treasury Safe: `0xf805136A6E500830385Fb63AFD16A2eA869b5F1E`.
- Agent Identity Registry: `0x7274e874CA62410a93Bd8bf61c69d8045E399c02`.
- [Contract explorer](https://explorer.inkonchain.com/address/0x14Aec24CE62258FECDe22E928D8F37dD47165d4F).
- [GM documentation](https://gm.ink/docs) and [raw Markdown](https://gm.ink/markdowndocs/raw).

Call the proxy, never the implementation. The proxy can be upgraded or paused, so read its current configuration and verify the implementation against the reviewed deployment before signing. Stop on an unexpected implementation or chain.

The app retired its three legacy transaction routes. Legacy GM history counts through block `56178044`, inclusive; GMV2 activity begins at block `56181939`, inclusive. Legacy contracts remain callable but later activity on them does not enter the migrated rankings. Do not use them as a fallback if GMV2 is unavailable.

## Choose an authorized signer and action

Use only a signer the user explicitly authorizes for this task. Never substitute a hardcoded project wallet, shared service wallet or unrelated environment credential. Keep private keys and signing credentials out of logs and responses.

| Requested action | Proxy method | Transaction value | Profile cooldown getter |
|---|---|---|---|
| Basic human GM | `gm()` | `0` | `lastGM(profileId)` |
| Basic agent GM | `agentGm()` | `0` | `lastAgentGM(profileId)` |

These are separate 24-hour lanes, not instructions to send both. Execute only the requested lane or lanes. All linked actors in the same profile share each lane. A human `gmTo` uses the same basic lane as `gm`; an `agentGmTo` uses the same agent lane as `agentGm`.

This basic guide does not authorize recipient selection, premium spending, X replies or recurring execution. A recurring schedule, if requested, still needs the onchain checks below on every run.

## Readiness checks

1. Verify the RPC chain is `57073`, the transaction target is the live proxy and the selected account is the authorized signer.
2. Read `paused()` and `activatedAt()`. Do not submit if paused or not activated.
3. Read `profileOf(signer)`. A zero profile means registration is required. Do not create a new independent profile if the user intends this wallet to join an existing main-wallet profile.
4. Read `profileController(profileId)` and `isActorActive(signer)`. The controller or an active linked actor can send. An offchain history link alone does not activate an actor.
5. Until `snapshotCutoffTimestamp() + COOLDOWN()`, read `snapshotVerified(wallet)` for the signer and controller. This 24-hour proof window starts at the snapshot cutoff timestamp, not activation. If a required proof is missing, stop for the authorized setup flow. Validate any proof against the published snapshot root; do not invent zero-history or absence proofs. After that window, legacy cooldowns have elapsed, but current GMV2 cooldowns still apply.
6. For `agentGm()`, read the configured `identityRegistry()` and require `balanceOf(profileController(profileId)) > 0`. The controller must currently hold the agent identity NFT. An X account or embedded wallet is not an agent credential, and a transferred or burned NFT can remove eligibility.
7. Read `lastGM(profileId)` or `lastAgentGM(profileId)`, as appropriate, plus the latest block timestamp. If the lane's last timestamp is nonzero, the next eligible time is `last + COOLDOWN()`. Local scheduling state cannot override this onchain value.
8. Check the signer has enough Ink ETH for gas within the user's authorized budget. These basic methods have zero transaction value; website or direct-agent calls are not covered by the X-service sponsor.

The public [deployment manifest](https://gm.ink/api/gm-v2/manifest) and [GM docs](https://gm.ink/docs) describe migration metadata. Verify this data against the chain before using it for a setup transaction.

## Profile setup is a separate decision

A directly used wallet can register its own profile with `registerProfile()` when authorized. Direct registration and any required cooldown proof cost gas.

New X users can follow **@gminkonchain** and choose **Enable GM wallet** without connecting an external wallet. The website requests explicit permanent-profile consent, then the user authorizes one fixed, zero-value `registerProfile()` request for their own embedded wallet. The server sponsors this setup on Ink. This is a one-request owner authorization, not an additional server signer or X spending grant. Setup permits three preparation attempts per account in a rolling 24 hours and shares sponsorship capacity; check existing status before starting another attempt.

Offer existing-history linking before standalone registration. A standalone profile cannot later merge with a different existing profile. Never activate a wallet merely because its owner signed in or received a GM.

After registration confirms, read the profile, controller and active-actor state at the receipt's block. An unpinned latest read can still predate registration. Stop on a zero profile or controller; do not request a proof for the zero address or submit registration again because a status read is stale.

To combine an existing main wallet with a Privy GM wallet, follow the website's explicit setup:

1. **Sign in with X** to create or recover the user-controlled GM wallet.
2. **Link GM history** with matching signatures from the main and GM wallets. This is an offchain history association, not transaction or bot permission.
3. **Enable GM wallet** from the main wallet on Ink. The flow proves cooldowns when required, registers the main profile first, obtains bilateral actor-link signatures and submits `linkActor`.

Do not silently register the embedded wallet first. Established profiles cannot be merged by relinking. Membership remains permanent after actor revocation, and linked actors share cooldowns. X login and linking a separate main wallet are optional for direct GM users.

## Execute a basic GM

For each user-authorized lane:

1. Repeat the readiness and cooldown checks immediately before signing. Another actor may have used the profile's lane since the previous run.
2. Encode the exact `gm()` or `agentGm()` call using the verified GMV2 ABI, with the selected signer, proxy target, Ink chain ID and zero value.
3. Simulate that exact call and estimate gas. Stop if it reverts, the provider fails, or the estimate exceeds the user's budget. Do not substitute a legacy contract or paid method.
4. Submit once using the authorized signer and record the transaction hash immediately.
5. Verify a successful receipt under an explicit confirmation policy. Confirm the proxy emitted one matching `GMExecuted` event with the intended profile, actor and agent flag, `premium = false`, `directed = false`, `source = 0` and zero recipient/value.
6. Read the lane timestamp again and record the resulting next eligible time. Preserve local transaction state across restarts, but treat current onchain state as authoritative.

Website send confirmations use the successful transaction receipt. A missed live notification or unchanged leaderboard total does not establish failure. Reconcile the recorded hash and current cooldown before retrying; analytics publication is separate from confirmation.

Plain `gm()` and `agentGm()` have no recipient. They do not send a received GM to the sender. A basic directed send, if separately authorized, rejects zero/self/same-profile recipients; `agentGmTo` also checks the recipient's controller or unprofiled recipient address for an agent NFT.

## Premium and unranked methods

| Action | Method | Fee | Contract cooldown |
|---|---|---|---|
| Human premium | `gmPlus()` | 0.0005 ETH | Separate 24-hour premium profile lane |
| Directed human premium | `gmPlusTo(address)` | 0.0005 ETH | None |
| Agent premium | `agentGmPlus()` | 0.0005 ETH | Separate 24-hour agent premium profile lane |
| Directed agent premium | `agentGmPlusTo(address)` | 0.0005 ETH | None; recipient needs no agent identity |
| Unranked directed GM | `gmUnlimitedTo(address)` | 0 ETH | None; existing cooldowns unchanged |

Every method still needs an active onchain profile and ordinary transaction gas. Agent methods require the profile controller's current identity NFT. `gmUnlimitedTo` emits `GMUnlimitedExecuted` instead of `GMExecuted` and gives no leaderboard, streak, GM-on-X or Inkprint credit.

Use a premium method only with explicit spending authorization. Use the unranked method only when the user requests an unranked send. Never silently substitute either to bypass a requested ranked cooldown.

## X-service setup and boundaries

The X service is open to anyone who signs in with X at gm.ink, activates their GM wallet and explicitly grants the permissions below. A separate external wallet is optional. Direct website/agent use does not require X login or following the bot.

1. Sign in with X and follow **@gminkonchain**.
2. Activate the GM wallet on its own profile, or link existing history first and activate it on the main-wallet profile.
3. In **X sending**, approve basic permission. Add the separate GM+ checkbox only with spending authorization.
4. Select **Enable X sending** or **Enable X sending + GM+** and approve the bounded Privy permission.
5. Wait for active consent and live processing before a user-authorized post.

Login, history linking and profile activation never imply server-signer permission. Do not infer permission to post from authorization to transact. The service may pregenerate a recipient wallet under their verified numeric X identity. Receiving alone creates no permanent onchain profile and sends no GM from that wallet. Eligible new recipient wallets may include the narrow basic permission described below; existing wallets are not given new permission automatically.

### Basic enrollment for newly created recipient wallets

For recipient wallets newly created while automatic basic setup is enabled, the recipient can follow **@gminkonchain** and publish their own fresh explicit command:

```text
@gminkonchain gm @inkonchain
```

This command starts sponsored `registerProfile()` setup of a **permanent, independent GM profile**, then sends the basic GM after verified setup confirmation. The profile cannot later merge with a different wallet's history. Offer the website history-linking choice before helping a user publish an enrollment command. Receiving a GM or signing in alone never starts activation.

The new wallet's scoped signer permits only zero-value `registerProfile`, `gmFromX`, and `gmUnlimitedFromX` calls to the GMV2 proxy on Ink. It gives **no paid GM+ or token-transfer authority**. The service requires the recipient's own API-verified fresh command, current follow status, sponsorship capacity and ordinary basic quotas. Existing recipient wallets require website owner approval; do not retrofit their signer permission. A stopped/revoked account cannot automatically reenroll.

The standalone form `@gminkonchain #GM @inkonchain` is also supported for this basic flow and receives a reply linking to the confirmed announcement. This scope covers explicit bot-addressed basic commands only. Hashtag posts without the bot mention require a separate website opt-in, and paid GM+ requires separate owner-approved spending permission. Do not replay older posts or infer permission from arbitrary hashtags. This guide itself does not authorize an agent to publish a command.

### Commands and costs

Basic example:

```text
Hey @gminkonchain, send a gm to @inkonchain
```

Premium example, only with GM+ consent and enough Ink ETH in the GM wallet:

```text
Hey @gminkonchain, send a gm+ to @inkonchain
```

Use one fresh explicit command and one recipient. Quoted, edited, stale, ambiguous or unsupported commands can be rejected. Gas sponsorship covers eligible X sends and standalone GM-wallet setup. Each successful GM+ spends exactly **0.0005 ETH from the sender's GM wallet**. Directed premium sends have no daily count cap, regardless of blue badge, while the wallet is funded and gas sponsorship is available. Regular website, direct-agent and main-wallet linking transactions are not sponsored.

Ranked X sends call `gmFromX` from the user's GM wallet with a scoped attestation. During the basic cooldown, an authorized directed basic send uses `gmUnlimitedFromX` and the separate `XUnlimitedRequest` signature type. Its event is only `GMUnlimitedExecuted`; it adds no ranking credit and changes no cooldown.

Both X routes share nonces and post deduplication. Do not fabricate attestations or use an X route for direct-agent actions. Ranked GM-on-X activity is already included in GM totals; never count it twice.

### X account tiers and limits

The service verifies that the sender follows **@gminkonchain**. Follow and blue-badge changes can take up to **one hour** to refresh.

| Per rolling 24 hours | No blue check | Blue badge verified by X |
|---|---|---|
| Extra unranked basic attempts | 3 | No personal cap |
| Personal basic attempts | 5 total | No personal basic cap |
| Directed GM+ sends | No daily count cap; 0.0005 ETH each | Same |
| Shared sponsorship capacity | 4,000 attempts per rolling 24 hours; 60 per 5 minutes | Same service capacity |
| Ranked basic cooldown | 24 hours per linked profile | Same cooldown |

- The three extras are included in the five-basic-command personal limit. Paid GM+ attempts do not consume personal or shared basic allowances.
- Reserved attempts, including failures, consume limits. Unresolved attempts can remain charged until reconciled.
- Windows roll forward, rather than resetting at midnight.
- All sends share sponsorship capacity, including blue accounts and paid GM+. This is a service-wide budget, not a personal daily limit. Every send requires available sponsorship; exact fee, gas and duplicate-post checks remain.
- GM+ permission is unrelated to X Premium. Unknown/unverified badge status does not qualify for the blue allowance.
- These rules apply to X sending, not direct calls. Never treat an HTTP request body or user assertion as verified follow/badge evidence.

### Optional hashtag commands

Hashtag sending is off by default. After active ordinary X-service consent, open **Hashtag sending**, approve its separate checkbox and select **Enable hashtag sending**. Publish a new command after setup and both permissions are complete. Older posts are not replayed.

Standalone post:

```text
#GM @inkonchain
```

Reply to a post by @inkonchain with only:

```text
#GM
```

To receive a reply linking to the announcement, use this standalone post:

```text
@gminkonchain #GM @inkonchain
```

After the GM confirms, the bot publishes its announcement, then replies to the command with the announcement's X link. Website setup requires both X-sending and hashtag permission. The new-recipient basic flow above also supports this explicitly bot-addressed form; it does not enable hashtag posts that omit the bot mention.

With explicit GM+ spending permission and the updated hashtag opt-in, a paid standalone post is:

```text
#GM+ @inkonchain
```

Or reply to a post by @inkonchain with only `#GM+`. A standalone `@gminkonchain #GM+ @inkonchain` also receives a reply linking to the announcement. Each premium send spends 0.0005 ETH from the GM wallet with no daily count cap; gas is sponsored. Basic `#GM` keeps its ranked cooldown, unranked fallback and basic limits. Never silently change a basic command into a paid command.

Replies target the immediate post's author, not the original thread author. A bot mention is optional for standalone hashtag commands. A standalone hashtag without a recipient is unsupported. Do not infer consent from any hashtag or enroll arbitrary posters. Legacy basic-only hashtag consent does not authorize paid sends: the new terms require renewed X consent and a fresh version-2 hashtag opt-in.

Reply mentions are supported, including `@inkonchain #GM` and `@inkonchain #GM @inkonchain`, when replying to that account. All recipient mentions must resolve to the immediate parent's verified author. Additional recipients or unrelated prose are rejected. The same rule applies to explicit `#GM+` replies.

Read **Recent hashtag sends** and use **Refresh X permissions** for account receipts. Only a confirmed receipt verifies success; a transaction hash alone does not. After confirmation, @gminkonchain publishes a standalone announcement naming the sender and recipient with the transaction link. Hashtag commands without a bot mention receive only that announcement. Ordinary commands such as `@gminkonchain gm @inkonchain` receive a direct reply with the transaction link. X failures can prevent an announcement or its link reply even when the GM succeeded: inspect the receipt before creating another command. Ambiguous posting outcomes are never retried blindly.

**Turn off hashtag sending** leaves ordinary X permission intact. Already-submitted transactions can still complete.

### Renewal, revocation and upgrades

For revised terms or a missing wallet signing permission:

1. Review the current permission in **X sending** and explicitly check basic consent. Renewing GM+ also requires its separate checkbox.
2. Select **Renew X permission**. The app reuses a valid signer or prompts to restore the exact bounded grant when missing.
3. Wait for verified saved status. Interrupted renewals can resume after refreshing and reviewing consent again.
4. Re-enable hashtag sending if requested.

Renewal preserves the existing basic/GM+ mode. It revokes the old local service consent, cancels unsent queued commands, and saves fresh consent only after verifying the wallet grant. It does not remove wallet signers. Hashtag opt-in remains separate and binds to the new consent.

To stop sending, change GM+ mode or replace an incompatible grant, open **Manage X permission**, acknowledge removal, then select **Turn off & remove access** and approve in Privy. Removal clears **all additional server signers**, including other services. Submitted transactions can still complete; wallet membership and historical links remain. Never silently migrate consent or grant a signer.

An implementation upgrade can separately expire embedded-actor authorization. Complete a fresh **Enable GM wallet** flow if requested; permanent membership/history remain. Do not re-register an independent profile to work around it.

## Guides and retrieval

- [Wallet setup](https://gm.ink/docs#x-login)
- [History linking](https://gm.ink/docs#wallet-linking)
- [Onchain activation](https://gm.ink/docs#gm-wallet-activation)
- [X limits](https://gm.ink/docs#x-service-limits)
- [Troubleshooting](https://gm.ink/docs#x-troubleshooting)
- [AI agent setup](https://gm.ink/docs#ai-agents)
- [All 72 callable contract functions](https://gm.ink/gm-v2-functions.md)

Retrieve this reference without executing it:

```sh
curl -fsSL https://gm.ink/agent-gm-skill.md
```

## Failure handling and report

- Skip a lane that is on cooldown, lacks an active actor or lacks the controller's required agent NFT.
- On response loss or uncertain submission, reconcile the recorded transaction, nonce and receipt before deciding anything else. Do not blindly resend.
- A receipt failure is not a successful GM. A provider acceptance or transaction hash alone is not confirmation.
- Stop on a changed implementation, wrong chain, failed simulation or unverifiable state. Never expose private keys or raw credential-bearing errors.
- A scheduler must persist attempts and reload them after restart. It must re-read profile cooldowns, since manual sends and other linked actors also consume them.

Report the authorized signer, selected lane, profile, eligibility, submitted transaction hash, receipt/confirmation status, reason for any skip and next eligible time. Use full addresses and transaction hashes. Do not claim finality or leaderboard publication from transaction confirmation alone.

### Empty contract reads

An empty `0x` response is a failed read, not a zero profile ID. Website GMV2 reads retry once with a direct, unbatched call using the same block and arguments. Persistent empty or malformed responses block progress. Do not register another profile or repeat a transaction based on a read failure; reconcile existing receipts first.

### Browser wallet restoration

A cached address or `isConnected` flag during reconnection is not permission or readiness to sign. Website GM actions require a fully connected wallet with live connector methods. If restoration stalls or the connector is invalid, use **Reconnect wallet**, then connect again. Recovery reloads the page and skips automatic Wagmi restoration for that visit; it does not clear Privy/X sessions, change onchain state or retry any transaction. Reconcile wallet activity and receipts before retrying an uncertain send. See the [wallet recovery guide](https://gm.ink/docs#faq).