x402 for beginners: from your first wallet to your first paid request

If you are a developer who wants to charge AI agents for an API but has never set up a crypto wallet, this x402 beginner's guide is for you. It starts from nothing, explains the handful of crypto ideas you actually need, and ends with a Laravel route that takes a real test payment you can watch in your wallet and in Requestway. You will not spend any money until you decide to go live.

The five ideas you need, and nothing more#

You do not need to understand blockchains to accept x402 payments. You need these five things:

There is one more word you will meet: facilitator. It is a service your Laravel app calls to check a payment and put it on the blockchain. It pays the transaction fee (called gas), so neither you nor the payer needs to hold any other coin. For testing, the free facilitator at https://x402.org/facilitator needs no account.

The most important point: your server only ever needs your address, never your recovery phrase or private key. The agent paying you signs the payment. Your app checks it and asks the facilitator to submit it. Money moves straight from the agent's wallet to yours; nothing in the middle holds it.

Step 1: create a wallet#

Install a self-custodial wallet: one where you, not a company, hold the recovery phrase. Popular choices include MetaMask and Rabby; any wallet that supports Ethereum-style (EVM) networks and lets you add Base will do. A wallet app is not the same as an account on a crypto exchange.

When you create the wallet:

1. Write the recovery phrase on paper, in order, and store it somewhere safe and offline. Do not screenshot it, email it to yourself or paste it into a notes app or password field on a website.
2. Set a strong password for the app. This protects the wallet on this device only; the phrase is what recovers it anywhere.
3. Copy your address. It starts with 0x and has 40 characters after that.

The same address works on every EVM network, so the one address receives test payments on Base Sepolia today and real payments on Base later. Some wallets hide test networks by default; you may need to switch on "show test networks" in settings to see Base Sepolia balances. You can always look an address up on the block explorer instead: sepolia.basescan.org for testnet and basescan.org for mainnet.

Two habits worth forming from day one:

• Use a dedicated wallet for your API's earnings, not the one you use for anything else. It keeps your accounts tidy and limits what any single mistake can touch.
• Check the address character by character whenever you paste it into config. Blockchain payments cannot be reversed or cancelled. Money sent to a mistyped address is gone.

Can you use an address from a crypto exchange instead? It is possible, but a wallet you control is the safer default: exchanges decide which networks and tokens they credit, and none of them give you a Base Sepolia address for testing. Start with your own wallet.

Step 2: install x402 in your Laravel app#

With an address in hand, the Laravel side takes a few minutes. You need PHP 8.2 or newer and Laravel 12 or 13. No blockchain node and no special PHP extension are involved.

composer require requestway/laravel-x402
php artisan x402:install
php artisan migrate

x402:install asks three questions:

1. Which wallet address should payments go to? Paste the address from step 1. The installer refuses anything that is not a valid 0x address.
2. Which network? Choose Base Sepolia, the recommended default. Nothing real can move on it.
3. Facilitator URL. Accept the default, https://x402.org/facilitator.

It writes these to your .env:

X402_PAY_TO=0xYourWalletAddress
X402_NETWORK=eip155:84532
X402_FACILITATOR_URL=https://x402.org/facilitator

eip155:84532 is Base Sepolia's network ID. Base mainnet is eip155:8453; you will not need it until the end of this guide. The migration is optional but useful: it records every payment attempt in an x402_payments table.

Step 3: put a price on a route#

Pick a route and add the middleware with a price in US dollars:

use Illuminate\Support\Facades\Route;

Route::get('/market-data', MarketDataController::class)->middleware('x402:0.01');

That route now answers 402 Payment Required to anyone who has not paid, with a header listing the price, the network and your address. An x402 client reads it, signs a payment of $0.01 in USDC, and retries. Your controller runs only once the payment checks out. If x402 itself is new to you, What is x402? walks through the exchange.

Check it immediately, without a wallet, a blockchain or a cent:

php artisan x402:test /market-data

This plays both sides against a fake facilitator: it shows the 402 with your address and price, then a paid 200. If you see "The full exchange works", your route is wired correctly. Then run the config check:

php artisan x402:doctor

It confirms your address format, network, facilitator and database setup, and tells you plainly what is wrong if anything is.

Step 4: connect Requestway#

Requestway shows you what your route earns and why payments fail. It is free, and like the package it never touches your money.

1. Create a free account and a project. You get two keys: rw_test_… for testing and staging, rw_live_… for production. Copy them when they are shown.

2. Add the test key to your .env:

   Copy

   X402_PLATFORM_KEY=rw_test_your_key
   

3. Make sure a queue worker runs, because reports are sent from a queued job after each response:

   Copy

   php artisan queue:work
   

The package now reports every settled, failed and observed payment to your project. It sends the route, price, network, your receiving address and the transaction hash. It never sends the payer's address. The install guide covers the details.

Step 5: take your first real test payment#

So far nothing has touched a blockchain. Now you make a real payment, on the testnet, without buying anything.

Deploy your app somewhere public over HTTPS (staging is ideal), then open your project in Requestway and go to the Test endpoint tab. Paste the full URL of your paid route, for example https://staging.example.com/market-data, and run it. Requestway acts as the agent:

1. It calls your route without paying and expects the 402.
2. It checks the payment terms a real client needs: network, token, your address.
3. It signs a payment with test USDC from its own wallet and retries. You do not need test funds for this.
4. It reads the receipt your app returns and links the transaction on the block explorer.
5. It waits up to 20 seconds for your app's own report to arrive in your project.

Click the transaction link: you will see test USDC moving from Requestway's test wallet to your address on Base Sepolia. That is exactly what a real agent payment looks like, minus the real money. The payment also appears in your Requestway dashboard under Testnet, separate from anything real. The endpoint tester only ever pays on testnets and never spends real money; a route that only accepts mainnet gets its 402 checked and nothing more.

If a step fails, the tester tells you which one and why. The usual beginner mistakes are a route that is not publicly reachable, a missing queue worker (step 5 times out), or a typo in X402_PAY_TO. Testing on Base Sepolia covers paying from your own script, and why x402 payments fail explains each error code.

Step 6: going live with real money#

When the testnet flow works, going live changes three things:

X402_NETWORK=eip155:8453
X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
X402_PLATFORM_KEY=rw_live_your_key

• Network: Base mainnet, where USDC is real.
• Facilitator: the free x402.org facilitator only settles testnet payments, so mainnet needs a production one. Coinbase Developer Platform runs one; it requires an account and signs each request, which the package supports through a small class you point X402_FACILITATOR_AUTH at. Facilitators explained covers the options.
• Key: switch to your rw_live_ key so real earnings are kept apart from your tests.

Your wallet address does not change: it is the same address on Base. Before you flip the switch, run php artisan x402:doctor again and work through the testnet to mainnet checklist. If you are unsure whether anyone will pay, run a week in observe mode first (X402_MODE=observe): nothing is charged, but you see what each route would have earned. Observe mode explains how.

When real payments arrive, they are USDC on Base in your wallet. You can hold it, send it on, or move it to an exchange that accepts USDC deposits on Base if you want to convert it to your own currency. Check the network carefully whenever you send USDC anywhere: sending on the wrong network is the most common way people lose funds.

Keeping it safe#

• Never put your recovery phrase or private key on a server, in .env, in a repository or in a support ticket. x402 does not need them, so nobody legitimate will ever ask.
• Keep the recovery phrase offline. If your laptop dies, the phrase is how you get the money back.
• Treat X402_PAY_TO as critical config. Changing it changes where your money goes. Review it in deploys like you would a database password.
• Start small on mainnet. Make one real payment of a cent and see it arrive before you rely on it.

FAQ#

What wallet do I need to accept x402 payments?#

Any self-custodial wallet that supports EVM networks, such as MetaMask or Rabby. You only give your app the wallet's address. The same address receives on Base Sepolia for testing and Base for real payments.

Do I need to buy crypto to start accepting x402 payments?#

No. Receiving needs only an address, and the facilitator pays the transaction fees. For testing, Requestway's endpoint tester pays your route with its own test USDC, so you can complete a full payment without buying or holding anything.

Is it safe to put my wallet address in my Laravel .env file?#

Yes. An address is public by design; it is where people send you money. What must never go in .env or on a server is your recovery phrase or private key, and x402 never needs either.

Why can't I see my test USDC in my wallet?#

Many wallets hide test networks by default. Turn on test networks in the wallet's settings and switch to Base Sepolia, or search your address on sepolia.basescan.org, which always shows the incoming transfers.

How do I get the USDC I earn out of my wallet?#

It is yours to move like any other USDC on Base: send it to another wallet, or to an exchange account that accepts USDC deposits on the Base network if you want to convert it to cash. Always double-check the network and address before sending.