agents-marketplace/docs/buyer/README.md

Vector Buyer App

A self-contained app for commissioning AI compute on the Vector L2 testnet. You submit prompts, bond AP3X in on-chain escrow, and receive LLM responses from supplier nodes; the escrow settles in AP3X on accepted work.

How It Works

1. You type a prompt and set a price in the web UI
2. The app posts an escrow transaction on-chain, locking price + bond
3. The app sends the task to a supplier node via HTTP
4. The supplier calls an LLM, claims the escrow, and submits the result hash on-chain
5. You see the response in the UI and can accept to release payment, or dispute

All on-chain settlement happens automatically. You just interact with the web UI.

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 buyer
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)
BUYER_MNEMONIC=word1 word2 word3 ... word15

# Supplier URLs (comma-separated)
SUPPLIER_URLS=http://SUPPLIER_IP:9000

# Port to run on (default 8080)
BUYER_PORT=8080

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 buyer wallet needs AP3X to pay for compute tasks and escrow bonds. You need at least 10 AP3X to get started.

When you start the app, the UI header shows your wallet address and balance. Send AP3X to that address.

6. Start the app

python main.py

You will see:

Starting Vector Buyer App on port 8080
UI: http://localhost:8080

7. Open the web UI

Go to http://localhost:8080 in your browser.

Using the Web UI

Submitting a Task

1. Type your prompt in the text area
2. Set the payment amount with the slider (in AP3X)
3. Select a supplier from the dropdown
4. Click Submit Task
5. Wait for the response (typically 15-40 seconds)

The app will:

• Post the escrow on-chain (locks payment + 1 AP3X bond)
• Send the task to the supplier
• Display the response when ready

Accepting a Result

After receiving a response, click Accept & Pay to release payment to the supplier. This completes the on-chain escrow lifecycle.

If you do not accept:

• Your payment stays locked in escrow
• After the dispute window (10 minutes), the supplier can collect payment automatically
• You lose your bond (1 AP3X) as a penalty for not responding

Task History

Click Task History in the nav bar to see all past tasks. Click any task to expand it and see full details including TX hashes.

Connecting to a Supplier

You need at least one supplier URL. The supplier operator will give you their URL.

Same machine (testing):

SUPPLIER_URLS=http://localhost:9000

Local network:

SUPPLIER_URLS=http://192.168.1.50:9000

Remote / internet:

SUPPLIER_URLS=http://supplier.example.com:9000

Multiple suppliers:

SUPPLIER_URLS=http://supplier1.com:9000,http://supplier2.com:9000

The app auto-discovers which suppliers are online and shows them in the dropdown.

File Structure

buyer/
  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_manager.py      Orchestrates the full buy flow
  escrow_ops.py        On-chain escrow transactions
  supplier_client.py   HTTP client for talking to suppliers
  discovery.py         Auto-discovers online suppliers
  storage.py           Task history (JSON file)
  .env                 Your configuration (secret - do not share)
  .env.example         Template for .env
  requirements.txt     Python dependencies
  static/
    app.html           Web 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
BUYER_MNEMONIC	Your 15-word wallet seed phrase	(required)
ESCROW_SCRIPT_HASH	Escrow contract hash	Pre-configured
RESOLVER_ADDRESS	Dispute resolver address	Pre-configured
SUPPLIER_URLS	Comma-separated supplier URLs	(required)
BUYER_PORT	HTTP port for the web UI	8080

Cost Breakdown

Each task costs:

• Payment: The amount you set (e.g. 5 AP3X) - goes to the supplier
• Buyer bond: 1 AP3X - returned to you when you accept
• TX fees: ~0.2-0.5 AP3X per transaction (escrow post + accept = 2 TXs)

If you accept the result, you get your 1 AP3X bond back. Total cost = payment + fees.

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.
• Escrow protects you: the supplier cannot take your escrowed value without delivering a result
• You have a 10-minute dispute window after receiving a result

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 buyer/ folder

"No supplier URL provided"

• Add at least one supplier URL to SUPPLIER_URLS in your .env

"0 suppliers available" in the UI

• The supplier node may be offline. Check with the supplier operator.
• Verify the URL is correct and reachable from your machine.

Balance shows 0 or very low

• Fund your wallet by sending AP3X to the address shown in the UI header.

Task fails with timeout

• The supplier may be overloaded. Try again or use a different supplier.
• Check your internet connection to both the supplier and the Vector testnet.