Link to an account
Updated:
A wallet buys on its own — nothing on this page is needed to use the x402 API. But when the agent pays for a company that already has a Proxy-seller account, the owner of that account can link the wallet of the agent to it. After that new orders of the wallet appear in the dashboard of the account, and its top-ups go to the balance of that account.
Linking is confirmed by both sides: the account by the session of its owner, the wallet by a signature. Signing does not move funds: it is not a transaction, it costs no gas and it does not switch the network of the wallet.
The flow
The owner asks for a message
In the dashboard, section Balance, the owner enters the address of the wallet and gets a one-time message for it.
The wallet signs it
personal_sign(EIP-191) of the message, exactly as received. The owner puts the signature back into the dashboard.The wallet is linked
From now on new orders of this wallet appear in the dashboard of the account and its top-ups go to the balance of the account.
The message
The message is an EIP-4361 text, the same kind Recover access uses, issued by the dashboard rather than by the x402 API.
Property | Value |
|---|---|
Lifetime | 5 minutes, one use, issued to one account |
Signing |
|
Regular wallet | The signature is checked with |
Smart-contract wallet | Checked through EIP-1271, and the contract has to be deployed on Base already — at least one transaction from it. A wallet that is not deployed yet cannot be linked |
Multisig | A Safe that needs several owners to sign is impractical here: the message lives 5 minutes |
An agent signs it the way it signs a recovery challenge:
// viem
await account.signMessage({ message });
// ethers
await wallet.signMessage(message);What changes
What | After linking |
|---|---|
Orders paid after linking | visible in the dashboard of the account, next to the orders bought there |
Top-ups from the wallet | go to the balance of the account |
Auto-renewal of these orders | paid from the balance of the account |
Payments for orders | unchanged: USDC from the wallet, the same two-request cycle |
Access tokens | unchanged: the API still authorizes by the access token of the order and by the signature of the wallet |
Recover access | the |
Withdrawals | still requested only by the wallet, with a signature (Withdraw balance), but paid out of the balance of the account, and only up to what this wallet topped up to that account minus what it has already withdrawn. The balance the wallet had before the linking can be withdrawn only after unlinking |
These orders belong to the account: the owner manages them in the dashboard and through the main API, and the agent keeps managing them through the x402 API with their access tokens.
What the wallet bought before
Orders paid before the linking, and the balance the wallet had then, stay with the wallet: they are not moved to the account. The agent keeps managing those orders through the x402 API as before, and their auto-renewal is still paid from that old balance. While the wallet is linked, Recover access shows the balance of the account instead, and the old balance can be withdrawn only after unlinking. Right after the linking the dashboard shows how much was left on that balance.
Unlinking
The owner can unlink the wallet at any time, and the wallet signs nothing for that. After unlinking, new payments from the wallet are its own again, while the orders bought while it was linked and the money already credited to the account stay with the account.
A wallet belongs to one account at a time: if it is linked somewhere else, it has to be unlinked there first. A blocked wallet cannot be linked at all — write to [email protected].