I paid but my units are not credited¶
USDC top-ups are not open yet. While the top-up status reads OPENS SOON, no top-up can be paid, so there is nothing to credit. Top-ups open first on Solana devnet, for listed testers only; mainnet comes later. The rest of this page describes how a top-up will be credited once they open.
Check the top-up status¶
The status endpoint is public and needs no key:
| Reply | Status | Meaning |
|---|---|---|
"status": "disabled" |
OPENS SOON | Top-ups are off; nothing can be paid |
"status": "operational" with a devnet network |
OPEN · DEVNET | Listed testers can top up with devnet test USDC |
"status": "degraded" |
DELAYED | Top-ups are running slowly; payments may settle late |
| no answer | UNAVAILABLE | The status could not be read; try again shortly |
network is a CAIP-2 id; devnet is solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1.
While top-ups are off, the prepare, submit and receipt endpoints answer 503 with
code topup_disabled. Once devnet opens, an account that is not on the tester list gets
403 with code topup_not_allowed.
How a top-up will be credited¶
Top-ups use x402 v2: USDC on Solana, with Coinbase Developer Platform as the facilitator that verifies and settles each payment. The facilitator pays the Solana network fee, so the paying wallet needs USDC only. Aetelier never receives or stores wallet keys.
A top-up is two HTTP calls. Prepare answers 402 with the price in
PAYMENT-REQUIRED and a memo that names this top-up. Submit carries the signed
payment in PAYMENT-SIGNATURE, and its reply says where the payment stands:
| Submit reply | code |
Meaning | What to do |
|---|---|---|---|
200 |
settled |
Settled on-chain and credited once; the reply carries the receipt, a PAYMENT-RESPONSE header and, when available, your new balance |
Nothing |
202 |
settling |
Submitted, but settlement is not confirmed yet; the platform keeps rechecking it in the background | Do not pay again; fetch the receipt by memo after the Retry-After delay |
409 |
verify_rejected |
The facilitator rejected the payment; nothing was credited | Start a new top-up |
409 |
intent_failed |
This memo already failed; the reply carries its receipt | Read receipt.failure in the receipt table below |
410 |
intent_expired |
The signing window closed before the payment was submitted | Start a new top-up |
503 |
verify_unavailable |
The facilitator could not verify the payment; nothing was credited | Start a new top-up after the Retry-After delay |
503 |
topup_unavailable |
Top-ups are starting or the payment network is unreachable; the payment was not sent | Start a new top-up after the Retry-After delay |
Each credit is keyed to the payment's on-chain signature, so one payment never credits twice. Repeating a submit for the same memo returns its current receipt, never a second credit. A public, signed payer CLI that waits for settlement and reads the receipt for you is coming.
Fetch the receipt by memo¶
Read the receipt with the API key of the account that started the top-up. A memo that
is unknown or belongs to another account gets 404 with code memo_not_found:
curl -s https://aetelier.xyz/api/payments/topups/<memo> \
-H "Authorization: Bearer $AETELIER_API_KEY"
The reply is 200 in every state. Read receipt.state:
receipt.state |
Meaning |
|---|---|
settled |
Credited once; signature is the on-chain transaction |
settling |
Still being checked; pending_signature, when present, is the transaction the facilitator reported |
failed with failure: not_landed |
No matching transaction was found yet; the platform keeps rechecking for up to 24 hours |
failed with failure: verify_rejected |
Final; nothing was credited |
expired |
Final; the payment was never submitted |
open |
Prepared, not yet submitted |
A settled top-up also shows in your ledger history with reason topup.
Still not credited: email support¶
Email [email protected] if the receipt reads settled but your balance has not
moved, or if USDC left your wallet and the receipt still reads failed after 24
hours. Include:
- the
memo; - the transaction signature, from the receipt or your wallet history;
- the network, from
receipt.network; - the bundle
skuand the approximate time, with timezone.
Never send keys
Support never needs your wallet keypair file, private key or seed phrase, or your API key. Do not send them to anyone. See Official channels.
Response targets are in the support policy.
Refunds¶
Units are prepaid, non-transferable service credits, not money. Bundle purchases are final except where the law requires a refund (Terms of Service §6). Send refund requests to [email protected] with the same memo, signature and network.
Related¶
- Units and the 402 error — what units fund, and what a short balance means
- Getting help — the escalation path and the status page
- Error-code index — platform API error codes