DEV Community

Cover image for Give Your AI a $5 Budget: Try x402 with a Real Order
Max
Max

Posted on Originally published at growvib.com AI-assisted

Give Your AI a $5 Budget: Try x402 with a Real Order

#ai #tutorial #blockchain #x402

Most agent tutorials end with a tool call that prints JSON. What if yours ended with a real order and an assistant checking what happened after it paid?

I recently added x402 support to GrowVib, the social media marketing platform I’m building. Here’s a small experiment you can build around it: compare services, approve a purchase within 5 USDC, and track the result.

You’ll work through HTTP payment challenges, wallet signing, budget checks, and asynchronous fulfillment. Discovery and quoting can be explored without paying.

Disclosure: I build GrowVib. This is an integration walkthrough, not a promise of marketing results. Paid orders use real funds, and the snippets illustrate parts of the application rather than a complete runnable project.

How the pieces fit together

MCP gives the assistant tools for finding services and requesting quotes. x402 adds a payment step to an HTTP request. Your wallet signs the payment, and GrowVib uses PayAI as its facilitator to verify and settle it.

Component Job
AI assistant Understand your requirements and explain options
GrowVib MCP Expose catalog and quote tools
Buyer wallet and x402 client Sign and submit an approved payment
GrowVib Request payment and manage the service order
PayAI Verify and settle payments on GrowVib’s side. No buyer setup required.
Your application Enforce spending limits and remember order state

You do not need to run a facilitator to buy from GrowVib. Your buyer application needs a compatible x402 client and wallet signer.

What you need

  • A tool-capable AI assistant or coding assistant.
  • A local Node.js/TypeScript application to coordinate the workflow.
  • GrowVib’s public MCP connection or its documented HTTP API.
  • An x402 v2 client with a compatible wallet signer.
  • USDC on Base mainnet for the approved purchase.
  • Persistent storage for approvals, budget reservations, and order references.

This guide focuses on Base. The 5 USDC budget covers service payments, while model usage, subscriptions, and wallet funding costs are separate.

Use a target you control and a service you understand. Check the destination platform’s rules before ordering. Automating a purchase does not guarantee genuine audience interest, organic reach, or sales.

1. Compare services without paying

Connect your compatible MCP client to:

https://api.growvib.com/mcp-public
Enter fullscreen mode Exit fullscreen mode

Follow your client’s remote-MCP setup instructions. The GrowVib x402 documentation also links to the HTTP API.

Try this prompt:

Help me compare GrowVib services without buying anything.

Platform: [platform]
Service type: [specific service]
Target URL: [a target I control]
Quantity: [quantity]
Audience requirements: [requirements or no preference]
Maximum wallet settlement: 5 USDC

Use the current tool schemas and actual catalog data.
Show up to three suitable options, with exact prices and
documented differences. Tell me if nothing matches.

Do not submit a paid request or sign any payment.
Enter fullscreen mode Exit fullscreen mode

Use search_catalog or recommend_service, then get_quote. Let the assistant read the current schemas instead of guessing arguments.

Check that the proposal identifies the service, target, quantity, conditions, and price before continuing.

2. Inspect an HTTP 402 response

This is an unpaid order request. Replace the placeholders with valid values from the selected service:

curl -i -X POST https://api.growvib.com/v1/agent/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "service_id": "<selected-service-id>",
    "quantity": 1000,
    "link": "<authorized-target-url>"
  }'
Enter fullscreen mode Exit fullscreen mode

The quantity is illustrative and must satisfy the service’s limits. A valid payable request without payment returns a 402 challenge. Invalid inputs may return a validation error instead.

Inspect the amount, asset, network, recipient, and expiration window.

Use ordinary HTTP for this preview. A payment-enabled wrapper may automatically pay when it receives a challenge.

3. Set up the buyer client

You need two things: an x402 client that speaks version 2 of the protocol, and a wallet signer it can use.

You do not need anything from PayAI. In this flow, the buyer does not contact the facilitator. Your client signs a payment and sends it to GrowVib. GrowVib calls its facilitator to verify and settle, and the outcome comes back in GrowVib’s response.

Version 2 is required. GrowVib puts the payment terms in a PAYMENT-REQUIRED header and expects the signed payload in PAYMENT-SIGNATURE.

A version 1 client sends X-PAYMENT instead. That request is rejected with a validation error. If you are evaluating a library, check which header it sends before anything else.

Set it up in this order:

  1. Configure the wallet signer locally and confirm the address it will pay from.
  2. Exercise the client against an endpoint you know supports it. GrowVib publishes no test endpoint, so treat this as a test of your client rather than of the integration.
  3. Configure Base mainnet and fund the paying address with USDC.
  4. Keep automatic payment switched off until the approval and budget checks work.
  5. Read the payment terms from GrowVib’s live 402 response. Do not hardcode an amount, asset, network, or recipient from an example, including this guide.

Keep the wallet key and any bearer token GrowVib returns out of chat transcripts, source control, and logs.

4. Make the $5 limit real

“Never spend more than $5” states your intent. The application has to enforce it before signing anything.

Track wallet settlements and account balance separately.

Wallet settlements: USDC that has left your wallet. The 5 USDC cap applies to this total. Keep it across requests and application restarts.

Account balance: Money that has already settled and now sits with GrowVib under your wallet address. Spending it debits that balance without a new on-chain settlement. Balance purchases still need approval for the exact order.

Use the balance you already paid for

GrowVib sets a $1 minimum settlement while orders are priced according to the catalog.

For example, an order costing $0.40 settles $1 when funded by a new minimum settlement. The remaining $0.60 stays as account balance.

If you treat every small order as a fresh settlement, you can keep paying the $1 floor while leaving those remainders unused.

A successful order response returns an agent_token. To spend an available balance, send it as a bearer token with an idempotency_key and no payment payload:

curl -X POST https://api.growvib.com/v1/agent/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <agent-token>' \
  -d '{
    "service_id": "<selected-service-id>",
    "quantity": 1000,
    "link": "<authorized-target-url>",
    "idempotency_key": "<your-unique-key>"
  }'
Enter fullscreen mode Exit fullscreen mode

The idempotency_key is required on this path.

A signed payment has retry protection tied to its authorization. A balance order has no payment signature, so the key prevents a timeout and retry from creating two orders and debiting twice.

Generate one key per intended purchase. Reuse that key when retrying the same purchase.

If the balance does not cover the order, the request returns an ordinary 402 challenge. Handle that as a new payment decision: inspect the settlement amount, check the remaining budget, and obtain approval before signing.

Check new settlements in code 

// Illustrative application logic, not x402 SDK code.
// USDC has six decimal places.
const budget = 5_000_000n;

function assertWithinBudget(
  settled: bigint,
  reserved: bigint,
  requested: bigint,
) {
  if (requested <= 0n) {
    throw new Error("Invalid payment amount");
  }

  if (settled + reserved + requested > budget) {
    throw new Error("Not enough budget remaining");
  }
}
Enter fullscreen mode Exit fullscreen mode

Persist the budget and reserve funds atomically before signing. Otherwise, two concurrent requests can pass the same check and overspend together.

Bind approval to the service, target, quantity, network, asset, recipient, and amount. If any approved detail changes, ask again. Restrict payments to the intended API host.

Watch the expiry

The payment terms expire, with a five-minute window by default. A manual approval can take longer than that.

Get approval first, then request fresh payment terms. Compare them with the approved service, target, quantity, network, asset, recipient, and amount.

If those details still match, sign within the new validity window. If they changed, ask again.

5. Approve one purchase

Keep the confirmation easy to review:

Service: [selected service]
Target: [approved URL]
Quantity: [approved quantity]

Order charge: [quoted amount]
Available GrowVib balance: [current amount]
Payment route: [account balance or new wallet settlement]
Wallet settlement: [required amount, or zero for a balance order]
Remaining settlement budget: [remaining amount]

For a new settlement:
Network: [network from live payment terms]
Asset: [asset from live payment terms]
Recipient: [recipient from live payment terms]

Approve this exact purchase?
Enter fullscreen mode Exit fullscreen mode

These are placeholders for live values.

For a balance order, submit the bearer token and the purchase’s idempotency key without a payment signature.

For a new settlement, fetch fresh payment terms after approval, check that the approved details still match, and only then sign.

Keep approval manual for the first version. You can learn the protocol without starting with unattended spending.

6. Track delivery after payment

Here is an illustrative successful order response for the $0.40 example:

{
  "order_id": "...",
  "tracking_code": "...",
  "status": "PENDING",
  "charged_usd": 0.40,
  "balance_usd": 0.60,
  "payment_id": "...",
  "agent_token": "..."
}
Enter fullscreen mode Exit fullscreen mode

charged_usd is the order cost. In this example, balance_usd is the remaining $0.60, available for later orders without another settlement.

Store both values, plus order_id and agent_token.

Read delivery status with the order ID and token:

curl 'https://api.growvib.com/v1/agent/orders/<order-id>' \
  -H 'Authorization: Bearer <agent-token>'
Enter fullscreen mode Exit fullscreen mode

This read accepts the bearer token as its credential. A payment signature does not replace it.

Without a token, you get a 401. Another account’s order returns 404.

Lost an order ID? GET /v1/agent/orders returns a page of your orders, newest first, with optional status, page, and page_size parameters.

Both reads are safe to poll. The endpoint is limited to 20 requests per minute per IP, so check periodically instead of running a tight loop. Respect Retry-After and back off when rate limited.

Renew the token without paying again

The token expires after an hour and is refreshed on every order.

An application that keeps ordering within that window and saves the returned token can keep its credentials current. A daily digest, however, will need to renew its token.

Sign in with the wallet instead of making another payment:

curl -X POST https://api.growvib.com/v1/agent/auth/challenge \
  -H 'Content-Type: application/json' \
  -d '{"address": "<your-wallet-address>"}'
Enter fullscreen mode Exit fullscreen mode

The response contains a nonce and a message.

For the Base wallet used here, sign the message bytes unchanged with personal_sign, then exchange the signature:

curl -X POST https://api.growvib.com/v1/agent/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"nonce": "<nonce>", "signature": "<signature>"}'
Enter fullscreen mode Exit fullscreen mode

You receive a fresh agent_token and the wallet’s current balance_usd. This does not make a payment or an on-chain transaction.

The nonce is single use, and a failed attempt consumes it. Request a new challenge for each attempt.

A Solana wallet includes "chain": "solana" in the challenge request and signs with signMessage.

Handle these responses explicitly

Payment success does not mean delivery is complete. Three responses deserve their own handling:

Response Meaning What to do
202, settlement_unresolved Settlement is uncertain and money may have moved Save the payment reference and reconcile before attempting another purchase
200, credited_no_order Payment settled, but no order was created Use the available balance, token, and an idempotency key to place the order
409, duplicate_order An order for that link is already in progress Use the existing order identified in the response

For settlement_unresolved, do not create a fresh signed payment. Record the payment_id and check your order list. If you need a token, use the wallet sign-in flow above.

An empty order list alone does not prove settlement failed. Keep the payment amount reserved while its outcome remains unresolved.

For partial delivery or refunds, report what the API says. Refunds are credited to your GrowVib account balance, not returned to the paying wallet. Refunds are not automatic.

If the endpoint returns 404

The x402 route returns 404 while it is switched off. Check GrowVib’s x402 documentation for current availability before assuming the URL is wrong.

Depending on the request, a 404 can also mean an unknown service or an order that does not belong to the authenticated account.

What could you build next?

Project Useful outcome
Comparison assistant Explain suitable options before purchasing
Client purchasing desk Keep budgets, approvals, and records separate
Order digest Summarize existing orders and exceptions
Repeat-order assistant Reuse requirements, obtain a fresh quote, and request approval

A scheduled digest needs a running application or scheduler. A chat does not keep checking orders after it ends.

Start with one clear task and one approved purchase. Add automation after you understand how the workflow behaves when something goes wrong.

The complete request and response flow is in the GrowVib x402 documentation.

What would you build first: a comparison assistant, a purchasing tool, or an order tracker?

Top comments (0)