Coming from REST

You already know how to call an API. This page is only about the handful of places where a blockchain does not behave like one, written for someone who has never touched Ethereum.

Start here: most of the app is just REST

The single most useful thing to know about integrating YouthChain: the social product runs entirely on normal HTTP. Engagement, rewards, profile, leaderboard, device fleet — all of it is fetch, JSON in, JSON out, no keys, no signing, no blockchain concepts at all.

What the app does	What you write
User likes, posts, comments, shares	`POST /api/mobile/engagement` — plain REST
Show earned rewards	`GET /api/mobile/rewards/:address` — plain REST
Show profile, score, rank	`GET /api/mobile/profile/:address` — plain REST
Leaderboard, activity feed	plain REST
Hold the user’s funds	← this is the part that needs a wallet
Move the user’s funds (swap, send, signed claim)	← and this

So the chain-specific work is confined to the wallet screens. Everything else you can build the way you build any product. If you are planning the work, that is where the estimate belongs.

The one rule that explains everything else

A write is a signed message that the network executes later, not a request the server performs now. Every difference below falls out of that sentence.

REST	Chain
`POST /orders` → `201` with the created object	Send a transaction → get a hash. The result exists ~2 blocks later
The server authenticates you (token, session)	Nobody authenticates you. Your signature proves who you are, and the network checks the math
`500` means it failed	A transaction can be included and still have failed — HTTP is `200`, the receipt says `status: 0`
Retrying is risky (duplicates)	Retrying the same signed transaction is safe: the nonce makes it the same transaction
Requests are free	Every write costs gas, paid in the native token
The server owns the data	The chain owns the data. You can read it without asking anyone

The six things to actually learn

An address (0x4444…) is an account. A private key is what proves you control it. There is no registration, no password reset, no “forgot my account”. The key never leaves the device and never goes to any server. Practical consequence: your onboarding must create a key and make the user back up the recovery phrase, because losing it loses the account. See Wallet Integration.

2. Nonce — a per-account counter that orders your writes

Every account has a counter. Transaction #7 cannot execute before #6. You read it right before signing:

const nonce = await provider.getTransactionCount(address, "pending");

Two transactions signed with the same nonce: only one survives, the other is dropped in silence. Sign one at a time, or read the nonce once and increment it yourself.

This is also why retries are safe. A retry of an already-signed transaction has the same nonce and hash, so the network treats it as the same thing — unlike a POST, which would create a second order.

3. Gas — writes cost money, reads are free

Executing costs gas, paid in the native token. On this testnet the price is fixed at 1 gwei and the faucet drops 0.1 YCE, which covers hundreds of transactions.

Reads (eth_call, eth_getBalance, any GET) cost nothing and are instant.
Writes cost gas and take a block.

The classic failure: a brand-new address has no native balance, so its very first transaction fails before doing anything. Fund first, act second.

4. Native YCE vs YCE token — the trap of this chain specifically

YCE exists in two separate places, and they are not the same balance.

	Native YCE	YCE token (ERC-20)
What it is	the chain’s built-in currency	a smart contract at `0x6a2247af…2f9ed`
Pays gas	✅ yes	❌ no
How you read it	`eth_getBalance(address)`	`balanceOf(address)` on the contract
Faucet gives	0.1	11,000

A user can hold 11,000 YCE tokens and still be unable to send a transaction, because gas is paid only by the native balance. Show them as two lines in the UI. Reading one and labelling it “your YCE” will produce support tickets. YCR is simpler — it only exists as a token — but it has its own pair:

pending YCR: earned by engagement, accrued inside the rewards contract. Read it at GET /api/mobile/rewards/:address.
YCR balance: real ERC-20, after a claim. Read it with balanceOf.

Pending is not spendable. Until the user claims, it is a promise, not a balance.

5. Amounts are integers with 18 decimals — and they overflow JavaScript

On-chain amounts have no decimal point. 1 YCE is 1000000000000000000 (10¹⁸).

Number("11000000000000000000000")   // ❌ 1.1e22 — precision already lost
BigInt("11000000000000000000000")   // ✅ exact
ethers.formatUnits(raw, 18)         // ✅ "11000.0" for display
ethers.parseUnits("11000", 18)      // ✅ back to the integer

Number.MAX_SAFE_INTEGER is about 9×10¹⁵ — smaller than one whole token. Use BigInt everywhere, convert to string for display only, and never do arithmetic on the formatted value.

6. The receipt is the real answer

Sending a transaction gives you a hash immediately. That means “accepted”, not “worked”.

const receipt = await provider.getTransactionReceipt(hash);
// receipt === null  → not mined yet, keep polling (every 5s — one block)
// receipt.status === 1 → succeeded
// receipt.status === 0 → included, executed, and reverted. Gas was spent.

A reverted transaction is the closest thing to a 400, and it arrives as a successful HTTP response with status: 0 inside. If your code only checks that the HTTP call worked, you will report success for a transfer that never happened. See Events & confirmations for cadences and the WebSocket alternative.

Mistakes that cost an afternoon

Symptom	Cause
”The balance is wrong / zero”	Read the native balance when you meant the token, or vice versa
”The transfer succeeded but nothing moved”	Called a contract address that has no code — a transfer to a codeless address succeeds and does nothing. Verify with `eth_getCode`
”Amounts are off by a rounding error”	`Number` instead of `BigInt`
”My second transaction disappeared”	Two signatures with the same nonce
”First transaction from a new user always fails”	No native balance for gas
”The receipt is null, so it failed”	It is not mined yet. The public RPC is an archive node and lags the validators slightly
”The user claimed but the balance did not change”	Pending YCR vs YCR balance — the claim moves one into the other

What you do not need to learn

To ship the social product: consensus, validators, DAG, staking, governance, the rollup. They matter to the protocol, not to your integration. If a page in Concepts is interesting, read it for context — none of it is a prerequisite for the app. Next: Quickstart to see it working, then Wallet Integration for the part that needs a key.

Get Started

Concepts

Resources

Start here: most of the app is just REST

The one rule that explains everything else

The six things to actually learn

2. Nonce — a per-account counter that orders your writes

3. Gas — writes cost money, reads are free

4. Native YCE vs YCE token — the trap of this chain specifically

5. Amounts are integers with 18 decimals — and they overflow JavaScript

6. The receipt is the real answer

Mistakes that cost an afternoon

What you do not need to learn

​Start here: most of the app is just REST

​The one rule that explains everything else

​The six things to actually learn

​1. Address and private key — there is no login

​2. Nonce — a per-account counter that orders your writes

​3. Gas — writes cost money, reads are free

​4. Native YCE vs YCE token — the trap of this chain specifically

​5. Amounts are integers with 18 decimals — and they overflow JavaScript

​6. The receipt is the real answer

​Mistakes that cost an afternoon

​What you do not need to learn

Start here: most of the app is just REST

The one rule that explains everything else

The six things to actually learn

1. Address and private key — there is no login

2. Nonce — a per-account counter that orders your writes

3. Gas — writes cost money, reads are free

4. Native YCE vs YCE token — the trap of this chain specifically

5. Amounts are integers with 18 decimals — and they overflow JavaScript

6. The receipt is the real answer

Mistakes that cost an afternoon

What you do not need to learn