Moove setup
Handle, default wallet, key scopes, and what a 409 means.
The account
Tollbooth is multi-tenant by construction: each tool author supplies their own Moove key, and payments settle directly to their own wallet. There is nothing in the middle. Before a key can create a payment link the account needs two things:Moove documentation
- A handle — the
@namepeople pay. - A default wallet — where money lands, and what it lands as.
Both are set at moove.xyz, not through the API.
The default wallet decides the chain
A payment link settles to the key owner’s default wallet, in that wallet’s chain and token. toAmount is denominated in that token, and the caller cannot choose a destination. So the wallet you set is the settlement chain for every link Tollbooth creates.Moove documentation
The API key and its scopes
Keys are created in the dashboard and shown once. A key is a down-scope of the user who issued it: it can request a payment and read links, and nothing else. No endpoint moves funds, so a leaked key can create requests that pay its owner — and nothing else.Moove documentation
| scope | grants | Tollbooth uses it for |
|---|---|---|
payment_link:create | Creating payment links | Opening a charge. |
payment_link:read | Listing payment links | The reconciliation sweep. Not for polling one link. |
You select an agent rather than raw scopes; the Receive agent expands to both. Polling a single link uses the public by-id read and needs no scope at all — see rate limits.
What a 409 means
409 PAYMENT_LINK_ACCOUNT_NOT_READY means the account itself is not set up to receive: no default wallet, or no handle. It is not transient and not a bug. Tollbooth surfaces it as MooveAccountNotReadyError with a message naming both things to set, and never retries it — retrying counts against the rate limit and fails identically. It is a setup-time check, so run it once when onboarding a tenant rather than discovering it on their first sale.
The other codes, and which are worth retrying, are on the troubleshooting page.
What the payer does
- Opens the checkout URL. No Moove account, no key, no signup, no KYC.Moove documentation
- Pays in any token on any of the 37 chains Moove supports; Moove routes and swaps to your settlement token.Moove documentation · Moove's own count
- For a payment link, the payer's wallet is debited enough to deliver your amount in full. The protocol fee is theirs.Moove documentation
receivedAmount equals toAmount in practice are marked pending on the results page.