agents-marketplace/docs/supplier/README.md

Vector Supplier Node

A self-contained AI compute supplier for the Vector L2 testnet (Cardano). You receive task requests from buyers, fulfill them with an LLM, and settle payment on-chain via escrow smart contracts.

How It Works

1. A buyer posts an escrow transaction on-chain, locking their payment + bond
2. The buyer sends you an HTTP request with the task prompt and escrow TX hash
3. Your node verifies the escrow exists on-chain
4. Your node calls the LLM to generate a response
5. Your node claims the escrow on-chain (Open -> Claimed)
6. Your node submits the result hash on-chain (Claimed -> Submitted)
7. The buyer reviews the response and accepts (releasing payment to you)

All on-chain steps happen automatically. You just need to keep this node running.

Quick Start

1. Install Python

You need Python 3.9 or newer. Download from https://www.python.org/downloads/

2. Create a virtual environment

cd supplier
python -m venv .venv

# Windows:
.venv\Scripts\activate

# macOS/Linux:
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Configure your environment

Copy the example file and fill in your values:

copy .env.example .env

Edit .env with your settings:

# Your wallet seed phrase (15 words)
SUPPLIER_MNEMONIC=word1 word2 word3 ... word15

# LLM API key from https://openrouter.ai
OPENROUTER_API_KEY=sk-or-v1-...

# Port to run on (default 9000)
SUPPLIER_PORT=9000

# Your node's display name
SUPPLIER_NAME=my-supplier

The other values (VECTOR_OGMIOS_URL, VECTOR_SUBMIT_URL, ESCROW_SCRIPT_HASH, RESOLVER_ADDRESS) are pre-configured for the Vector testnet and should not need changing.

5. Fund your wallet

Your supplier wallet needs ADA to pay transaction fees and post bonds. You need at least 5 ADA to get started.

When you start the node, it will print your wallet address. Send ADA to that address.

6. Start the node

python main.py

You will see:

Starting Vector Supplier Node 'my-supplier' on port 9000
Dashboard: http://localhost:9000

7. Open the dashboard

Go to http://localhost:9000 in your browser. The dashboard shows:

• Your wallet balance
• Total earnings
• Number of tasks completed
• Task history with full details (prompts, responses, TX hashes)

Giving Your URL to Buyers

Buyers need your URL to send you tasks. If you are running on:

• Same machine: http://localhost:9000
• Local network: http://YOUR_IP:9000 (find your IP with ipconfig on Windows)
• Public internet: You need to either:
  • Set up port forwarding on your router (forward port 9000)
  • Use a service like ngrok: ngrok http 9000
  • Deploy to a cloud server (AWS, DigitalOcean, etc.)

The buyer adds your URL to their SUPPLIER_URLS config and your node appears in their dashboard.

File Structure

supplier/
  main.py              Entry point - starts the web server
  config.py            Loads settings from .env
  wallet.py            Initializes blockchain wallet
  api.py               HTTP API endpoints
  task_runner.py        Orchestrates the full task flow
  escrow_ops.py         On-chain escrow transactions
  llm.py               LLM API client (OpenRouter/Anthropic/OpenAI)
  storage.py           Task history (JSON file)
  .env                 Your configuration (secret - do not share)
  .env.example         Template for .env
  requirements.txt     Python dependencies
  static/
    dashboard.html     Web dashboard UI
  lib/                 Blockchain utilities
    constants.py       Protocol constants
    chain.py           Chain query helpers
    datum.py           CBOR datum builders
    escrow_tx.py       Transaction builder
    blueprint.py       Smart contract loader
    protocol.py        API data models
  contracts/
    escrow/
      plutus.json      Compiled smart contract
  data/
    tasks.json         Task history (auto-created)

Configuration Reference

Variable	Description	Default
VECTOR_OGMIOS_URL	Blockchain node URL	Vector testnet
VECTOR_SUBMIT_URL	TX submission URL	Vector testnet
SUPPLIER_MNEMONIC	Your 15-word wallet seed phrase	(required)
ESCROW_SCRIPT_HASH	Escrow contract hash	Pre-configured
OPENROUTER_API_KEY	LLM API key from openrouter.ai	(required)
RESOLVER_ADDRESS	Dispute resolver address	Pre-configured
SUPPLIER_PORT	HTTP port	9000
SUPPLIER_NAME	Display name	default-supplier

Earnings

Payment is in AP3X (the Vector testnet token). 1 AP3X = 1,000,000 lovelace.

When a buyer accepts your response, the escrow releases:

• Your payment (set by the buyer, typically 3-10 AP3X per task)
• Your bond back (1 AP3X)
• The buyer's bond (1 AP3X bonus to you)

If the buyer does NOT accept within the dispute window (10 minutes), you can collect payment automatically.

Security Notes

• Never share your .env file - it contains your wallet seed phrase
• Never share your data/ folder - it contains task history
• The seed phrase controls your wallet. Back it up securely.
• The node only responds to buyers who have already locked value on-chain, so you cannot be scammed out of compute.

Troubleshooting

"No module named 'vector_agent'"

• Make sure you installed dependencies: pip install -r requirements.txt

"ogmios_url required"

• Make sure your .env file exists and is in the supplier/ folder

"Collateral check failed"

• Your wallet needs more ADA. Send at least 5 ADA to your supplier address.

Dashboard shows "Balance: unavailable"

• The Vector testnet node may be temporarily down. Wait and refresh.

Task fails with "UTxO not found"

• The buyer's escrow transaction hasn't propagated yet. The node retries automatically for up to 60 seconds.