Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for the x402 payment protocol on Stellar, including a new quickstart guide for building paid APIs. The PR also fixes relative path errors in existing x402 documentation and adds navigation structure through a category file.
Changes:
- Added a new quickstart guide (
quickstart-guide.mdx) with step-by-step instructions for building a paid x402 API with Node.js, Express, and Stellar settlement - Fixed relative path references in the x402 README that were self-referential or incorrectly navigated the file structure
- Added a category configuration file to properly organize x402 documentation in the navigation sidebar
- Updated the routes configuration to include the new quickstart guide route
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| routes.txt | Added new route for the x402 quickstart guide |
| docs/build/apps/x402/README.mdx | Fixed relative path links that had incorrect navigation depth |
| docs/build/apps/x402/quickstart-guide.mdx | New comprehensive quickstart guide with server and client code examples |
| docs/build/apps/x402/category.json | New category configuration file for x402 documentation organization |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
|
|
||
| This sends `$0.01` of testnet USDC from the client account to the server account. | ||
|
|
||
| The client then receives the protected JSON data: ```{ secret: "valuable content" }``` |
ElliotFriend
left a comment
ElliotFriend
left a comment
There was a problem hiding this comment.
looking really good! couple clarifications and some more details here-and-there, and it should be ready to go!
since you've got the routes.txt file already modified, you probably already ran the yarn build command, and my note about filepaths changing is probably moot.
thanks for the contribution!!
|
|
||
| This tutorial shows how to build the simplest possible paid API with Node.js and Express using the x402 packages with settlement on the Stellar network. | ||
|
|
||
| To follow this guide, you will need [Node.js](https://nodejs.org/) installed locally. Node.js 18 or newer is recommended so you can use the built-in fetch API. |
There was a problem hiding this comment.
nitpick-adjacent: i know that for the purpose of the "you need fetch here" idea in the sentence, node18 makes sense. but, it's EoL, so it might make sense to just recommend the currently active LTS version?
| npm install express dotenv @stellar/stellar-sdk @x402/core @x402/express @x402/fetch @x402/stellar | ||
| ``` | ||
|
|
||
| This creates a `package.json` and installs everything needed for both `server.js` and `client.js`. |
There was a problem hiding this comment.
doesn't package.json get created when we called npm init?
|
|
||
| Create a file named `server.js` and paste in the following code: | ||
|
|
||
| ```js title="server.js" |
There was a problem hiding this comment.
i'd love to see some more explanatory comments throughout big chunks like this. so as to explain some of the logic, as you go
|
|
||
| With your Express server running, create a file named `client.js` and paste in the following code: | ||
|
|
||
| ```js title="client.js" |
There was a problem hiding this comment.
same note as above, could use some explanatory comments throughout this chunk
|
|
||
| console.log(`Target: ${url}\nClient address: ${signer.address}`); | ||
|
|
||
| const firstTry = await fetch(url, { method: "GET" }); |
There was a problem hiding this comment.
i think fetch defaults to the GET method, right? if so, you could remove the object here, since it's not really doing anything.
| const firstTry = await fetch(url, { method: "GET" }); | ||
| console.log(`Payment requested: ${firstTry.status}`); | ||
|
|
||
| const paymentRequired = httpClient.getPaymentRequiredResponse((name) => |
There was a problem hiding this comment.
especially here, we could use an explanation of what the paymentRequired variable/function is/does/needs/etc.
| Next, create a fresh account and fund it with testnet XLM and testnet USDC using Stellar Lab: | ||
|
|
||
| - [Fund a testnet account in Stellar Lab](https://lab.stellar.org/account/fund) |
There was a problem hiding this comment.
you might need just a little bit more detail on how this process works. specifically about the trustline that's needed. i think the process goes like
- create the keypair
- fund with xlm
- create the USDC trustline (there's a button on that fund page), sign and submit that transaciton
- visit the circle faucet, select stellar testnet and paste your public key
would be nice to include some of those details.
| }); | ||
| ``` | ||
|
|
||
| Update `PAY_TO` with the Stellar address that should receive funds whenever a client pays for your service. |
There was a problem hiding this comment.
you may need to include a note that the PAY_TO account needs to be funded on testnet, and have the USDC trustline already
| x402 is an open protocol from the Coinbase Developer Platform that enables programmatic, per request payments over HTTP, designed especially for AI agents and APIs. It effectively turns the old “402 Payment Required” HTTP status code into something usable, for both humans and AI agents. | ||
|
|
||
| On Stellar, x402 works with Soroban authorization so that clients can pay for API requests via signed auth entries, ideal for micropayments and payment enabled apps. To build an x402-enabled service or integrate payments into your app, see [Build Applications](./README.mdx) and the resources below. | ||
| On Stellar, x402 works with Soroban authorization so that clients can pay for API requests via signed auth entries, ideal for micropayments and payment enabled apps. To build an x402-enabled service or integrate payments into your app, see [Build Applications](../README.mdx) and the resources below. |
There was a problem hiding this comment.
this maaaay not be necessary. it's kindof weird how docusaurus works with these. a file at path/to/directory/README.mdx might end up with an actual filepath of path/to/directory.html once the site gets built... 🤔 (i might be mixing up things in my memory, though)
if you've run yarn build successfully, it should be fine as-is
There was a problem hiding this comment.
same would (or wouldn't lol) hold true for the other filepaths modified in this file
| "label": "x402 on Stellar", | ||
| "position": 74, |
There was a problem hiding this comment.
these two are already defined in the frontmatter of the README.mdx file you're moving to, and aren't necessary in a cateogory json file. the README automatically becomes the category index.
Adds a new page to /docs/build/apps/x402/quickstart-guide
The guide covers:
Moved /docs/build/apps/x402.mdx to /docs/build/apps/x402/README.mdx