⚡ Conduit

Pay-per-call API marketplace powered by x402 payments on the Stacks blockchain.

AI agents autonomously discover, pay for, and consume APIs using HTTP 402 — no API keys, no subscriptions, just HTTP and STX.

---

Talent Protocol Update (April 2026): New features added for the hackathon event including on-chain analytics helpers, trust scoring enhancements, and a streamlined event submission flow. See EVENT_SUBMISSION.md for details.

---

The Problem

Today's API economy is broken for machines:

• Agents need API keys that require human account creation
• Rate limits and subscriptions assume human consumption patterns
• No protocol-level standard for machine-to-machine payments

The Solution

Conduit uses the x402 payment protocol to create a marketplace where:

• 🤖 AI Agents discover available APIs via a free catalog endpoint
• 🔒 Paid endpoints return HTTP 402 Payment Required with pricing
• 💎 The x402-stacks interceptor auto-pays in STX and retries
• ⚡ Data flows back — no accounts, no keys, no friction

Agent → GET /api/v1/price?symbol=BTC
Server → 402 Payment Required (0.005 STX)
Agent → Signs STX transfer via x402 interceptor
Server → 200 OK + { price: 97500.00, ... }

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Conduit Server                         │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ Free Layer   │  │ x402 Paywall │  │ API Services     │  │
│  │              │  │              │  │                  │  │
│  │ /discover    │  │ paymentMiddle│  │ Weather          │  │
│  │ /stats       │  │ ware()       │  │ Sentiment        │  │
│  │ /health      │  │              │  │ Translation      │  │
│  └──────────────┘  │ Validates    │  │ Crypto Prices    │  │
│                    │ payment-sig  │  │ Image Gen        │  │
│                    │ header       │  │ Code Review      │  │
│                    └──────┬───────┘  │ News             │  │
│                           │          │ Chain Analytics   │  │
│                    ┌──────▼───────┐  └──────────────────┘  │
│                    │ Facilitator  │                         │
│                    │ Settlement   │                         │
│                    └──────────────┘                         │
└─────────────────────────────────────────────────────────────┘

---

Quick Start

Prerequisites

• Node.js >= 18

# Clone
git clone https://github.com/YOUR_USERNAME/conduit.git
cd conduit

# Install
npm install

# Configure (optional — defaults work out of the box)
cp .env.example .env

# Run
npm run build
npm run dev

Open http://localhost:3402 in your browser.

---

API Reference

Free Endpoints

Endpoint	Method	Description
/api/v1/discover	GET	Full API catalog with pricing and docs
/api/v1/stats	GET	Marketplace analytics and recent transactions
/api/v1/health	GET	Server health check

Paid Endpoints (x402-protected)

Endpoint	Method	Price	Description
/api/v1/weather	GET	0.01 STX	Weather data and forecasts
/api/v1/sentiment	POST	0.02 STX	NLP sentiment analysis
/api/v1/translate	POST	0.015 STX	Neural machine translation
/api/v1/price	GET	0.005 STX	Crypto price oracle
/api/v1/generate-image	POST	0.05 STX	AI image generation
/api/v1/code-review	POST	0.03 STX	Automated code review
/api/v1/news	GET	0.008 STX	AI-curated news feed
/api/v1/chain-analytics	GET	0.02 STX	Stacks on-chain analytics

---

Agent Integration

Client (Auto-pay with x402 interceptor)

import axios from 'axios';
import { wrapAxiosWithPayment, privateKeyToAccount } from 'x402-stacks';

const account = privateKeyToAccount(process.env.PRIVATE_KEY, 'mainnet');

const api = wrapAxiosWithPayment(
  axios.create({ baseURL: 'http://localhost:3402' }),
  account
);

// Discover APIs (free)
const catalog = await api.get('/api/v1/discover');

// Use paid APIs — payment is automatic
const weather = await api.get('/api/v1/weather?location=Tokyo');
const price = await api.get('/api/v1/price?symbol=BTC');

Server (Monetize your own API)

import express from 'express';
import { paymentMiddleware, STXtoMicroSTX } from 'x402-stacks';

const app = express();

app.get('/api/premium',
  paymentMiddleware({
    amount: STXtoMicroSTX(0.01),
    payTo: 'YOUR_STACKS_ADDRESS',
    network: 'mainnet',
    facilitatorUrl: 'https://x402-facilitator.x402stacks.xyz',
    description: 'Premium data access',
  }),
  (req, res) => res.json({ data: 'Your premium content' })
);

---

Agent Demo

Run the interactive agent demo to see the full x402 flow:

npm run agent:demo

# Or with a specific task:
node agent-demo/agent.js "What's the price of Bitcoin?"
node agent-demo/agent.js "Translate hello to Spanish"
node agent-demo/agent.js "Get blockchain news"

---

Smart Contracts (Clarity)

Conduit includes 4 production-ready Clarity smart contracts that bring the marketplace logic on-chain:

1. api-registry.clar — On-Chain API Registry

Providers register APIs with pricing, descriptions, and metadata. Agents discover endpoints by reading contract state.

Function	Description
register-api	Register a new API with pricing and metadata
update-api-price	Update pricing for your API
toggle-api-status	Activate/deactivate an API
get-api-by-id	Read API details from chain
get-api-by-slug	Look up API by name slug

2. payment-escrow.clar — Payment Escrow & Settlement

Handles the full payment lifecycle: deposit → settle → dispute → refund. Includes platform fees and expiry-based auto-refund.

Function	Description
create-payment	Deposit STX into escrow for an API call
settle-payment	Release escrowed STX to provider
dispute-payment	Lock funds for admin review
refund-payment	Admin refund for disputed payments
claim-expired-escrow	Auto-refund after 24h if unsettled

3. reputation.clar — On-Chain Reputation System

Agents rate APIs after paid calls, building a trust layer. Includes 5 tiers: New → Bronze → Silver → Gold → Platinum.

Function	Description
rate-api	Submit a 1-5 star rating with comment
get-api-reputation	Full star distribution for an API
get-api-average-rating	Average rating (scaled ×100)
get-provider-reputation	Provider's aggregate score and tier
has-rated	Check if a user already rated an API

4. subscription-manager.clar — Prepaid Credits & Subscriptions

Agents deposit STX to get credits with volume discounts (up to 100% bonus). Subscription plans with block-based expiry.

Function	Description
purchase-credits	Buy credits with volume discounts
spend-credits	Use credits for API calls
subscribe	Subscribe to a prepaid plan
create-plan	Admin: create subscription plans
calculate-credits	Preview credits for a deposit amount

---

Tech Stack

• Runtime: Node.js + Express.js
• Protocol: x402-stacks (HTTP 402 payment protocol)
• Blockchain: Stacks L2 (secured by Bitcoin)
• Smart Contracts: Clarity (Stacks native language)
• Asset: STX (Stacks token)
• Frontend: Vanilla HTML/CSS/JS with premium design
• Settlement: x402 Facilitator service

---

Project Structure

conduit/
├── contracts/
│   ├── api-registry.clar        # On-chain API registration & discovery
│   ├── payment-escrow.clar      # STX escrow, settlement & disputes
│   ├── reputation.clar          # Rating system with provider tiers
│   └── subscription-manager.clar # Prepaid credits & subscription plans
├── server/index.js              # Express server with x402 middleware
├── public/
│   ├── index.html               # Marketplace UI
│   ├── css/styles.css           # Premium design system
│   └── js/app.js                # Frontend logic
├── agent-demo/agent.js          # AI agent demo script
├── package.json
├── .env.example
├── LICENSE
└── README.md

---

License

MIT — see LICENSE

---

Built for the x402 Stacks Challenge on DoraHacks