Your profile picture
This guide shows you how to use an NFT you own as your picture on Hartii. You choose it once, on hartiibiome.com/profile, and it follows your wallet address.
Who it's for: anyone with a wallet that holds an NFT on Quai Cyprus-1 (chain 9). You can set it on hartiibiome.com or on hartiilabs.com (Labs 1.22.0 and later). It is one picture per wallet, shared across all three sites.
What it is
Your picture is one NFT (an ERC-721 token) that your wallet owns. Hartii draws it in the round frame it already uses for your identity colours. If you have no picture, or it cannot be shown, you keep the identity colours, so nothing ever looks broken.
What you'll need
- A Pelagus or Blip wallet set to Quai Mainnet.
- An NFT in that wallet on Cyprus-1.
- No QUAI for gas. Setting a picture is free.
Steps
- Open hartiibiome.com/profile.
- Press Connect wallet. This shares your public address only. Nothing is signed yet.
- Under Choose a picture, find your NFT. The page lists the NFTs your wallet holds on Cyprus-1. Press Show more if you have many.
- Press Use this picture on the one you want.
- Your wallet asks you to sign a short message. Read it and approve. It names the site, the chain, your wallet, the NFT and a five minute expiry.
- The page shows your new picture. To change it, choose another NFT. To go back to your identity colours, press Remove picture and sign once more.
On HartiiLabs
You can do the same on hartiilabs.com:
- Connect your wallet and open your Profile page.
- Under Choose a picture, pick one of your NFTs. They are listed as neutral tiles with the name and token number, and the picture itself is served by hartiigames.com, the same service Biome and Games use.
- Sign the short message in your wallet. It is free, with no transaction and no gas.
- To go back to your identity colours, press Remove picture and sign once more.
If you set a picture on one site, it shows on all of them. You do not set it again.
It costs nothing
Setting or removing a picture is one free signature. No transaction is sent and no gas is spent. The signature only proves the wallet is yours. It cannot move your NFT or your QUAI, and each signature works once, for one action, for five minutes.
What to know
- Ownership is checked again whenever the picture is shown. If you sell or send the NFT, the picture stops showing and your identity colours return by themselves. You do not have to remove it.
- The choice is public. Anyone can see which NFT a wallet address uses as its picture.
- Only some images are shown. The picture has to be a PNG, JPEG, WebP or GIF of at most 2 MB. An SVG, a larger file or an image that cannot be read falls back to your identity colours.
- A picture is not a verified collection. Anyone can make a contract that looks like an NFT collection, so Hartii shows the contract address next to your picture on the profile page. Check it before you trust a picture.
Where it appears
- Hartii Games: the wallet chip in the header, the profile sheet (Me), and the leaderboards.
- Hartii Biome: the wallet chip in the header, the explorer address page, and the profile page.
- HartiiLabs (1.22.0 and later): the creator line on token pages, comments, leaderboard rows, the "Launches by" bar on the launch board, the wallet chip in the header, and the profile page.
If something goes wrong
| What you see | What to do |
|---|---|
| No NFTs listed | The wallet holds none on Cyprus-1, or the list could not be read. The page says which. Try again in a moment. |
| You declined the signature | Nothing was saved. Press Use this picture again. |
| The wallet does not own that NFT | Choose an NFT that is in this wallet now. |
| The picture shows as your colours | The NFT may have moved, or its image is not a PNG, JPEG, WebP or GIF under 2 MB. |
For developers
The service lives on hartiigames.com under /api/avatar, and any app can read pictures from it. Writing is for the wallet owner and needs a signature.
| Method and path | Auth | Returns |
|---|---|---|
GET /api/avatar/nonce?wallet=<address> | none | { nonce, expiresAt }, valid for 5 minutes, single use |
POST /api/avatar/set | wallet signature | { ok, wallet, contract, tokenId, image, setAt } |
POST /api/avatar/clear | wallet signature | { ok, wallet, avatar: null } |
GET /api/avatar/<wallet> | none | { wallet, contract, tokenId, image, setAt } or { wallet, avatar: null } |
GET /api/avatar/batch?wallets=a,b,c | none | { avatars: { ... }, pending: [wallet] }, up to 50 wallets |
GET /api/avatar/img/<wallet> | none | the image bytes, or 404 |
Wallets and contracts must be Cyprus-1 Quai-ledger addresses. image is a path on hartiigames.com; put https://hartiigames.com in front of it from another origin. Reads check ownership on the chain and reuse a good answer for 10 minutes. If the chain cannot be reached, a single read answers 503 and a batch lists the wallet in pending. It is never reported as "no picture".
To set a picture: ask for a nonce, sign the message below with personal_sign (EIP-191, hex-encoded UTF-8), then POST /api/avatar/set with JSON { "wallet", "contract", "tokenId", "nonce", "signature" }. The server rebuilds the message itself, so only the fields above are trusted.
Hartii profile picture
Site: hartiigames.com
Chain: Quai Cyprus-1 (chain 9)
Action: set
Wallet: <wallet, lowercase>
Contract: <contract, lowercase>
Token ID: <decimal>
Nonce: <nonce>
Expires: <expiresAt, as returned>
Signing proves you own this wallet. It does not send a transaction or cost gas.Lines end with LF and there is no trailing newline. For /api/avatar/clear, use Action: clear, Contract: none and Token ID: none. A set signature cannot be replayed as clear.
CORS. Writes from a browser are accepted only from https://hartiigames.com, https://hartiibiome.com and https://hartiilabs.com. Other browser origins get 403 origin_not_allowed. Requests without an Origin header (servers, <img> tags) work. There is no wildcard.
Errors are { "error", "code" }. Nothing is stored on any error.