Micropay Bazaar Documentation

You need a Solana wallet to receive payments and an API key to register.

1. Install Phantom wallet browser extension
2. Open Phantom → Settings → Developer Settings → switch to Devnet
3. Copy your wallet address (click the address at the top of Phantom)
4. Get free test SOL from faucet.solana.com

For authentication, use the demo key for all hackathon testing:

HeaderAuthorization: Bearer mp_live_demo_key

Call the registry endpoint with your service details. Once registered, AI agents can find and pay for your API.

cURLcurl -X POST https://micropay.up.railway.app/api/v1/registry/register \
  -H "Authorization: Bearer mp_live_demo_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Weather API",
    "description": "Real-time temperature, humidity, and wind for any city.",
    "endpoint": "https://my-api.com/weather",
    "cost_usd": 0.01,
    "developer_wallet": "YOUR_PHANTOM_WALLET_ADDRESS"
  }'

Response — 201 Created:

JSON{
  "id": "srv_a2k9xb3m7",
  "object": "service",
  "created_at": "2026-02-28T18:00:00.000Z",
  "name": "My Weather API",
  "description": "Real-time temperature, humidity...",
  "endpoint": "https://my-api.com/weather",
  "cost_usd": 0.01,
  "developer_wallet": "YOUR_PHANTOM_WALLET_ADDRESS"
}

Search the Bazaar to confirm agents can find you:

cURLcurl "https://micropay.up.railway.app/api/v1/registry/discover?query=weather"

Your service appears in the data array. You can also look it up directly:

cURLcurl https://micropay.up.railway.app/api/v1/registry/services/srv_a2k9xb3m7

When an agent pays for your service, the full flow is automatic:

1. Agent creates a charge with your service_id
2. Micropay builds an unsigned Solana transaction pointing to your developer_wallet
3. Agent signs with Phantom and broadcasts to Devnet
4. SOL lands in your wallet — settled in <1 second

Check your balance and transaction history:

cURL# Check SOL balance
curl https://micropay.up.railway.app/api/v1/balance/YOUR_WALLET_ADDRESS

# See last 5 transactions
curl https://micropay.up.railway.app/api/v1/transactions/YOUR_WALLET_ADDRESS

You need a Solana wallet with test SOL to pay for API calls.

1. Install Phantom wallet browser extension
2. Open Phantom → Settings → Developer Settings → switch to Devnet
3. Copy your wallet address (click the address at the top of Phantom)
4. Get free test SOL from faucet.solana.com (paste your address, request airdrop)

For API authentication, use the demo key:

HeaderAuthorization: Bearer mp_live_demo_key

Discover what's in the Bazaar. 26 services are preloaded across 11 categories.

cURL# Get all 26 services
curl https://micropay.up.railway.app/api/v1/registry/discover

# Search by intent
curl "https://micropay.up.railway.app/api/v1/registry/discover?query=stocks"

Each service has an id and a price category. See the full catalog for all 26 services. Note the id — you'll use it next.

This is the core payment step. You send a service_id and your source_wallet, and get back an unsigned Solana transaction.

cURLcurl -X POST https://micropay.up.railway.app/api/v1/charges \
  -H "Authorization: Bearer mp_live_demo_key" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "finance_stocks",
    "source_wallet": "YOUR_PHANTOM_WALLET_ADDRESS"
  }'

Response — the full charge object:

JSON{
  "id": "ch_wb4bedrhxh1q",
  "object": "charge",
  "status": "requires_signature",
  "service_id": "finance_stocks",
  "service_name": "Stock Price Feed",
  "amount_usd": 0.01,
  "exchange_rate_sol_usd": 148.32,
  "amount_sol": 0.000067423,
  "network_fee_sol": 0.000005,
  "source_wallet": "AuofYo21...Nt5",
  "destination_wallet": "2Hn6ESe...zv8",
  "transaction_payload": "AQAAAAAAAAAAAABAAQADb8d..."
}

Response fields explained

Decode the transaction_payload, refresh the blockhash (critical — it expires), sign with Phantom, and broadcast to Devnet.

JavaScript — Full signing flowimport { Transaction, Connection } from '@solana/web3.js';

// Connect to Solana Devnet
const connection = new Connection(
  'https://api.devnet.solana.com', 'confirmed'
);

// Step 4a: Decode the base64 payload from the charge response
const tx = Transaction.from(
  Buffer.from(charge.transaction_payload, 'base64')
);

// Step 4b: CRITICAL — Refresh the blockhash
// The blockhash from charge creation expires in ~60s.
// If you skip this, you get "Blockhash not found".
const { blockhash, lastValidBlockHeight } =
  await connection.getLatestBlockhash('confirmed');
tx.recentBlockhash = blockhash;

// Step 4c: Sign with Phantom (triggers wallet popup)
const signed = await window.phantom.solana.signTransaction(tx);

// Step 4d: Broadcast to Devnet
const signature = await connection.sendRawTransaction(
  signed.serialize()
);

// Step 4e: Confirm settlement
await connection.confirmTransaction(
  { signature, blockhash, lastValidBlockHeight }, 'confirmed'
);

console.log(`Done! https://explorer.solana.com/tx/${signature}?cluster=devnet`);

Instead of manual charges, send a natural language message to the AI Gateway. The AI decides if it needs a paid tool or can answer directly — then you handle the payment loop.

Step 5a — Send a message

cURLcurl -X POST https://micropay.up.railway.app/api/v1/chat/completions \
  -H "Authorization: Bearer mp_live_demo_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the current price of AAPL?",
    "source_wallet": "YOUR_PHANTOM_WALLET_ADDRESS"
  }'

If the AI can answer from knowledge, you get type: "message" — you're done. But if it needs live data, you get type: "tool_call":

tool_call response{
  "type": "tool_call",
  "conversation_id": "conv_a8f2k9x1b3",
  "message": "I need to access Stock Price Feed (~$0.01 in SOL).",
  "tool_call": {
    "id": "call_abc123",
    "service_id": "finance_stocks",
    "service_name": "Stock Price Feed",
    "estimated_cost_usd": 0.01
  }
}

Step 5b — Create a charge + sign + broadcast

Use the service_id from the tool call to create a charge (Step 3 above), then sign and broadcast (Step 4). This is the payment.

Step 5c — Fetch data from the service endpoint

After payment, call the service's endpoint to get the actual data. The endpoint is in the registry.

Step 5d — Send the data back to the AI

cURLcurl -X POST https://micropay.up.railway.app/api/v1/chat/tool-result \
  -H "Authorization: Bearer mp_live_demo_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_a8f2k9x1b3",
    "tool_result": "{\"AAPL\":{\"price\":189.42,\"change\":\"+1.2%\",\"volume\":\"58M\"}}"
  }'

Response — the AI gives a natural language answer:

JSON{
  "type": "message",
  "conversation_id": "conv_a8f2k9x1b3",
  "content": "Apple (AAPL) is currently trading at $189.42, up 1.2% today on volume of 58M shares.",
  "model": "gpt-4o-mini"
}

Full agentic flow in JavaScript

JavaScript — Complete AI agent loopasync function askAgent(question, wallet) {
  // 1. Ask the AI
  const chatRes = await fetch('https://micropay.up.railway.app/api/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer mp_live_demo_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ message: question, source_wallet: wallet })
  });
  const chat = await chatRes.json();

  // 2. If plain answer, we're done
  if (chat.type === 'message') return chat.content;

  // 3. AI needs paid data — create charge
  const chargeRes = await fetch('https://micropay.up.railway.app/api/v1/charges', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer mp_live_demo_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      service_id: chat.tool_call.service_id,
      source_wallet: wallet
    })
  });
  const charge = await chargeRes.json();

  // 4. Sign + broadcast (see Step 4 above)
  const tx = Transaction.from(Buffer.from(charge.transaction_payload, 'base64'));
  const { blockhash, lastValidBlockHeight } =
    await connection.getLatestBlockhash('confirmed');
  tx.recentBlockhash = blockhash;
  const signed = await phantom.signTransaction(tx);
  const sig = await connection.sendRawTransaction(signed.serialize());
  await connection.confirmTransaction(
    { signature: sig, blockhash, lastValidBlockHeight }, 'confirmed'
  );

  // 5. Fetch real data from service (your app logic here)
  const serviceData = await fetchFromService(chat.tool_call.service_id, question);

  // 6. Send data back to AI
  const resultRes = await fetch('https://micropay.up.railway.app/api/v1/chat/tool-result', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer mp_live_demo_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      conversation_id: chat.conversation_id,
      tool_result: JSON.stringify(serviceData)
    })
  });
  const result = await resultRes.json();
  return result.content;
}

// Usage
const answer = await askAgent("What is the price of AAPL?", "YOUR_WALLET");
console.log(answer);