> ## Documentation Index
> Fetch the complete documentation index at: https://docs.madra.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart for Buyers & Agents

> Search the Bazaar, pay for a resource, and handle rejections from your own code in under ten minutes.

You are building a wallet, an agent, or a script that pays for services. By the end of this page you will have found a paid endpoint on the Bazaar, paid for it, received the resource, and seen what a failure looks like. Everything else in the buyer docs expands on the pieces this page introduces.

## Prerequisites

* Node.js 22+ (or an equivalent runtime with the `@stellarx402/client` SDK)
* A Stellar wallet keypair funded with **Testnet USDC** ([faucet](https://laboratory.stellar.org/#account-creator))
* The facilitator URL (`https://facilitator.stellarx402.com` for the hosted version)

## 1. Install the client SDK

```bash theme={null}
npm install @stellarx402/client
```

## 2. Search the Bazaar

```typescript theme={null}
import { discover } from "@stellarx402/client";

const results = await discover({
  facilitator: "https://facilitator.stellarx402.com",
  query: "weather forecast",
  maxPrice: "0.01",
  network: "stellar:testnet",
});

console.log(results[0]);
// {
//   resource: "https://api.example.com/weather",
//   description: "5-day weather forecast by lat/lng",
//   scheme: "exact",
//   amount: "0.005",
//   asset: { symbol: "USDC", ... },
//   ...
// }
```

## 3. Pay for the resource

```typescript theme={null}
import { fetchWithPayment, StellarWallet } from "@stellarx402/client";

const wallet = StellarWallet.fromSecret(process.env.STELLAR_SECRET_KEY!);

const response = await fetchWithPayment(results[0].resource, {
  wallet,
  facilitator: "https://facilitator.stellarx402.com",
});

if (response.ok) {
  console.log(await response.json());
  console.log("Paid tx:", response.headers.get("x-payment-response"));
}
```

That is a complete paid request. `fetchWithPayment` handles the `402` challenge, builds and signs the payment, retries with the `X-Payment` header, and returns the resource response.

## 4. Handle a rejection

Not every payment will succeed, and the difference between "you are out of budget" and "that endpoint no longer exists" matters when nobody is watching your agent. Every rejection has a stable machine-readable code:

```typescript theme={null}
import { PaymentError } from "@stellarx402/client";

try {
  await fetchWithPayment(url, { wallet, facilitator });
} catch (err) {
  if (err instanceof PaymentError) {
    switch (err.code) {
      case "insufficient_funds": /* top up wallet */ break;
      case "resource_gone":       /* remove from queue */ break;
      case "price_changed":       /* re-fetch requirements */ break;
      default:                    /* see error reference */
    }
  }
}
```

Full list: [Error & Rejection Codes](/reference/error-codes).

## Where to go next

<CardGroup cols={2}>
  <Card title="Searching the Bazaar" icon="magnifying-glass" href="/guides/buyers/searching-the-bazaar">
    Filters, ranking, and pagination for the discovery API.
  </Card>

  <Card title="Handling Rejections" icon="triangle-exclamation" href="/guides/buyers/handling-rejections">
    Every machine-readable reason a payment can fail, and how an agent should react to each one.
  </Card>

  <Card title="Budgets & the Upto Scheme" icon="wallet" href="/guides/buyers/budgets-and-upto">
    Cap what an agent can spend across a session or per-tool, using smart account contracts.
  </Card>

  <Card title="MCP Integration for Agents" icon="plug" href="/guides/buyers/mcp-integration">
    Wire the Bazaar and the payment client into an MCP-speaking agent runtime.
  </Card>
</CardGroup>