Getting Started By x402

The x402 protocol (also known as L402) is an emerging standard for API monetization that enables pay-per-use access without requiring a subscription.

Minara x402 endpoint: https://x402.minara.ai

What is x402?

x402 is a native "pay-to-play" system for the web. Instead of pre-paying for a subscription, you pay for each API call directly using stablecoins like $USDC.

Key Benefits:

• No Subscription Required: Pay only for what you use

• Permissionless Access: No account creation or approval process

• Instant Activation: Start using APIs immediately after payment

• Crypto-Native: Payments in USDC on Base, Solana, or Polygon

• Transparent Pricing: Know exactly what each API call costs

How it works:

The x402 protocol follows a payment-challenge flow with these key steps:

The Complete Flow

1. Initial Request (Client → Server)

   • You make an API request to a protected endpoint without payment

2. Payment Challenge (Server → Client)

   • Server responds with 402 Payment Required status

   • Returns payment instructions (amount, currency, recipient address, chain)

3. Payment Selection (Client)

   • You select a payment method and create a payment payload

   • Prepare to pay with USDC on the specified chain

4. Authenticated Request (Client → Server)

   • Include payment proof in x-payment-response header

   • Retry the original request

5. Verification (Server → Facilitator)

   • Server sends payment proof to facilitator for verification

   • Confirms payment validity

6. Payment Processing (Facilitator → Blockchain)

   • Facilitator submits transaction to blockchain

   • Transaction confirmed on-chain

7. Settlement (Facilitator → Server)

   • Facilitator confirms settlement to server

   • Payment is finalized

8. Access Granted (Server → Client)

   • You receive the API response

   • Payment receipt included in X-PAYMENT-RESPONSE header

Key Components

• Client: Your application making API requests

• Server: Minara API endpoints (https://x402.minara.ai)

• Facilitator: Payment verification and settlement service

• Blockchain: On-chain payment settlement (Base, Solana, or Polygon)

---

How to Use x402 with Minara

1. Using x402 SDK (Recommended)

Most developers use the official x402 SDK which handles all payment flows automatically.

You just make requests: the SDK handles payment challenges, verification, and settlement for you.

Prerequisites

Before you begin, ensure you have:

• A crypto wallet with USDC (any EVM-compatible wallet)

• Node.js and npm, Go, or Python and pip

• Your wallet's private key (for signing payments)

Step 1: Install Dependencies

Node.js / TypeScript

# For fetch-based clients (recommended)
npm install @x402/fetch @x402/evm

# For axios-based clients
npm install @x402/axios @x402/evm

# For Solana support, also add:
npm install @x402/svm

Python

# For httpx (async) - recommended
pip install "x402[httpx]"

# For requests (sync)
pip install "x402[requests]"

# For Solana support, also add:
pip install "x402[svm]"

Go

go get github.com/coinbase/x402/go

Step 2: Set Up Your Wallet Signer

Node.js (using viem)

npm install viem

import { privateKeyToAccount } from "viem/accounts";

// Create a signer from private key (use environment variable)
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

For Solana:

import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

Python (using eth-account)

pip install eth_account

import os
from eth_account import Account
from x402.mechanisms.evm import EthAccountSigner

account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
signer = EthAccountSigner(account)

Go

import (
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

evmSigner, err := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))
if err != nil {
    log.Fatal(err)
}

Step 3: Make Requests: Payments Handled Automatically!

The SDK automatically handles payment challenges for you. Just make requests normally!

Node.js (with fetch)

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// Create signer
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// Create x402 client and register EVM scheme
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// Wrap fetch with payment handling
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// Make request - payment is handled automatically! 🎉
const response = await fetchWithPayment("https://x402.minara.ai/x402/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    userQuery: "What is the current price of BTC?"
  })
});

const data = await response.json();
console.log("Response:", data.content);

// Get payment receipt (optional)
if (response.ok) {
  const httpClient = new x402HTTPClient(client);
  const paymentResponse = httpClient.getPaymentSettleResponse(
    (name) => response.headers.get(name)
  );
  console.log("Payment settled:", paymentResponse);
}

📖 Full example on GitHub

Node.js (with axios)

import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import axios from "axios";

// Create signer
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// Create x402 client and register EVM scheme
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// Create an Axios instance with payment handling
const api = wrapAxiosWithPayment(
  axios.create({ baseURL: "https://x402.minara.ai" }),
  client
);

// Make request - payment is handled automatically! 🎉
const response = await api.post("/x402/chat", {
  userQuery: "Analyze ETH price action"
});

console.log("Response:", response.data.content);

📖 Full example on GitHub

Python (async with httpx)

import asyncio
import os
from eth_account import Account

from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


async def call_minara():
    # Create client and register EVM scheme
    client = x402Client()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    # Make request - payment is handled automatically! 🎉
    async with x402HttpxClient(client) as http:
        response = await http.post(
            "https://x402.minara.ai/x402/chat",
            json={"userQuery": "What is BTC price?"}
        )
        await response.aread()
        
        data = response.json()
        print(f"Response: {data['content']}")


asyncio.run(call_minara())

📖 Full example on GitHub

Python (sync with requests)

import os
from eth_account import Account

from x402 import x402ClientSync
from x402.http.clients import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


def call_minara():
    # Create client and register EVM scheme
    client = x402ClientSync()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    # Make request - payment is handled automatically! 🎉
    with x402_requests(client) as session:
        response = session.post(
            "https://x402.minara.ai/x402/chat",
            json={"userQuery": "What is BTC price?"}
        )
        
        data = response.json()
        print(f"Response: {data['content']}")


call_minara()

📖 Full example on GitHub

Go

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "time"

    x402 "github.com/coinbase/x402/go"
    x402http "github.com/coinbase/x402/go/http"
    evm "github.com/coinbase/x402/go/mechanisms/evm/exact/client"
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

func main() {
    // Create EVM signer
    evmSigner, _ := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))

    // Create x402 client and register EVM scheme
    x402Client := x402.Newx402Client().
        Register("eip155:*", evm.NewExactEvmScheme(evmSigner))

    // Wrap HTTP client with payment handling
    httpClient := x402http.WrapHTTPClientWithPayment(
        http.DefaultClient,
        x402http.Newx402HTTPClient(x402Client),
    )

    // Prepare request body
    reqBody := map[string]string{"userQuery": "What is BTC price?"}
    jsonData, _ := json.Marshal(reqBody)

    // Make request - payment is handled automatically! 🎉
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    req, _ := http.NewRequestWithContext(ctx, "POST", "https://x402.minara.ai/x402/chat", bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    
    resp, err := httpClient.Do(req)
    if err != nil {
        fmt.Printf("Request failed: %v\n", err)
        return
    }
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Printf("Response: %v\n", data["content"])
}

📖 Full example on GitHub

Multi-Chain Support (Base + Solana + Polygon)

You can register multiple payment schemes to support all Minara chains:

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { registerExactSvmScheme } from "@x402/svm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

// Create signers for different chains
const evmSigner = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

// Create client with multiple schemes
const client = new x402Client();
registerExactEvmScheme(client, { signer: evmSigner });  // Base + Polygon
registerExactSvmScheme(client, { signer: svmSigner });  // Solana

const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// Now you can call ANY Minara endpoint! 🚀
// Base endpoints
await fetchWithPayment("https://x402.minara.ai/x402/chat", {...});

// Solana endpoints  
await fetchWithPayment("https://x402.minara.ai/x402/solana/chat", {...});

// Polygon endpoints
await fetchWithPayment("https://x402.minara.ai/x402/polygon/chat", {...});

Complete Example: Chat with Minara

Here's a complete working example that calls Minara's AI chat endpoint:

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

async function chatWithMinara(query: string) {
  // 1. Set up signer
  const signer = privateKeyToAccount(
    process.env.EVM_PRIVATE_KEY as `0x${string}`
  );

  // 2. Create x402 client
  const client = new x402Client();
  registerExactEvmScheme(client, { signer });

  // 3. Wrap fetch
  const fetchWithPayment = wrapFetchWithPayment(fetch, client);

  // 4. Make request - SDK handles payment automatically!
  const response = await fetchWithPayment("https://x402.minara.ai/x402/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ userQuery: query })
  });

  const data = await response.json();
  return data.content;
}

// Usage
const answer = await chatWithMinara("What is the current price of BTC?");
console.log(answer);
// Output: "BTC is currently trading at $98,450. Key support levels..."

For more information, please check the official x402 documentation: Quickstart for buyers

---

2. Manual Payment Flow (Without SDK)

If you prefer not to use the SDK, you can handle payments manually:

Step 1: Make Initial Request

curl -X POST https://x402.minara.ai/x402/chat \
  -H "Content-Type: application/json" \
  -d '{"userQuery": "What is BTC price?"}'

Step 2: Receive Payment Challenge

{
  "error": "payment_required",
  "message": "Payment required to access this resource",
  "paymentInstructions": {
    "amount": "0.20",
    "currency": "USDC",
    "recipient": "0xCF5815e9063FA0b04Be0Cb5C1DB583eeF9ef5fbB",
    "chain": "base"
  }
}

Step 3: Pay with Wallet

Use MetaMask, Phantom, or any Web3 wallet to send USDC to the recipient address.

Step 4: Retry with Payment Proof

curl -X POST https://x402.minara.ai/x402/chat \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{"userQuery": "What is BTC price?"}'

Step 5: Get Response

{
  "content": "BTC is currently trading at $98,450..."
}

---

Error Handling

Common Errors from Minara API

402 Payment Required

{ "error": "payment_required" }

→ Normal! SDK will handle this automatically.

401 Unauthorized

{ "error": "unauthorized", "message": "Invalid payment response token" }

→ Payment proof invalid or expired. SDK will retry.

400 Bad Request

{ "error": "bad_request", "message": "Missing required parameter: userQuery" }

→ Check your request body has required fields.

Rate Limits

x402 endpoints are rate-limited per wallet address:

• AI Endpoints: 60 requests/minute

• Trading Endpoints: 30 requests/minute

If you exceed limits:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again in 30 seconds.",
  "retryAfter": 30
}

---

Resources & Support

📚 Official x402 Resources

• x402 Protocol Documentation

• Quickstart for Buyers

• x402 GitHub Repository

• x402 Discord

📦 NPM Packages

• @x402/fetch - Fetch wrapper

• @x402/axios - Axios interceptor

• @x402/evm - EVM support (Base, Polygon)

• @x402/svm - Solana support

• x402 Python Package

🔍 Minara Specific

• Minara on x402scan - View all endpoints

• Minara API Reference (x402) - API Reference (x402)

API Reference

API Reference (x402)