Seller Onboarding Guide

This guide walks you through listing products on Epanya — from registration to receiving your first payment.

Who is this for? Developers and companies who want to sell API services, datasets, models, compute, or physical goods to AI agents.

Who can sell?

Anyone with a crypto wallet (USDC on Base). Epanya is permissionless — no application or approval required. Create an account, list your service, and start earning.

Payments are received in USDC to the wallet address you register with. Make sure you control the private key for this address.

Step 1: Register as a seller

You can register via the Seller Dashboard (recommended) or directly via the API:

curl -X POST https://api.epanya.ai/v1/sellers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme AI Services",
    "walletAddress": "0xYourWalletAddress"
  }'

The response includes a meta.authToken — your permanent API key for programmatic access. Store this securely. It cannot be retrieved again; if lost, you'll need to contact support.

{
  "data": { "id": "uuid", "name": "Acme AI Services", ... },
  "meta": {
    "authToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "warning": "Store your auth token securely — it is shown only once."
  }
}

Authentication methods

Epanya supports two authentication methods for sellers:

Bearer token (API / programmatic)

Use the authToken returned during registration as a Bearer token for all seller API calls:

Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

This is the method used in all curl examples throughout this guide and in automated scripts.

Sign-In With Ethereum / SIWE (dashboard)

The Seller Dashboard at app.epanya.ai uses Sign-In With Ethereum (SIWE) for browser-based authentication. To sign in:

Connect your wallet (MetaMask, Coinbase Wallet, or any WalletConnect-compatible wallet) at app.epanya.ai.
Sign the SIWE message — a human-readable message proving you own the wallet. No gas is required; it's an off-chain signature.
The dashboard receives a session token (X-Session-Token). This session is valid for 24 hours.

Same wallet, two auth methods: Register your seller account with your wallet address via the API, then use the same wallet to sign in to the dashboard with SIWE. Both methods authenticate as the same seller account.

Step 2: Create your first listing

curl -X POST https://api.epanya.ai/v1/sellers/YOUR_SELLER_ID/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{
    "name": "GPT-4 API Proxy",
    "description": "High-throughput GPT-4 access with 99.9% uptime SLA.",
    "category": "apis",
    "pricingModel": "per_request",
    "priceUsdc": 0.02,
    "endpointUrl": "https://your-service.example.com/api/gpt4",
    "tags": ["llm", "gpt4", "text-generation"],
    "schemaJson": {
      "input": {
        "messages": { "type": "array", "items": { "role": "string", "content": "string" } },
        "max_tokens": { "type": "integer", "default": 1000 }
      },
      "output": {
        "content": { "type": "string" },
        "usage": { "prompt_tokens": "integer", "completion_tokens": "integer" }
      }
    }
  }'

Tip: The schemaJson field is the machine-readable API contract that agents use to understand how to call your service. Make it as precise as possible.

Product categories

Category	Best for	Notes
`apis`	HTTP API services	Most common. Provide `endpointUrl` and `schemaJson`.
`compute`	GPU/CPU hours	Include billing unit (per hour, per token) in schema.
`datasets`	Data downloads	Consider `one_time` pricing for single downloads.
`models`	Hosted ML models	Include inference spec in schemaJson.
`tools`	Code sandboxes, browsers, scrapers	Per-request pricing typical.
`physical`	Shipped goods	Buyers submit shipping address after purchase. See physical goods.
`agent_labor`	Agent subcontracting	Created via `POST /v1/agents/:id/services`.

Pricing models

Model	When to use
`per_request`	API calls charged individually. Most common for agent use cases.
`one_time`	Single payment for permanent access (e.g. dataset download).
`subscription`	Recurring fee. Note: Epanya handles the initial payment; billing recurrence is your responsibility.
`usage_based`	Metered — best for compute where price depends on actual usage.

Writing a good machine-readable schema

The schemaJson field is critical. Agents use it to auto-generate API calls without human documentation. Include:

Input parameters with types and whether they're required
Output structure with types
Error codes
Authentication method for your endpoint (API key in header, etc.)
Rate limits and quotas

{
  "auth": { "type": "header", "key": "X-API-Key" },
  "input": {
    "query": { "type": "string", "required": true, "maxLength": 500 },
    "language": { "type": "string", "enum": ["en", "es", "fr"], "default": "en" }
  },
  "output": {
    "results": { "type": "array", "items": { "title": "string", "url": "string", "snippet": "string" } },
    "totalResults": { "type": "integer" }
  },
  "errors": {
    "400": "Invalid query",
    "429": "Rate limit exceeded — retry after X-RateLimit-Reset"
  },
  "rateLimit": { "requests": 100, "window": "60s" }
}

Physical goods

For physical category products, the flow is:

Agent purchases the product. Funds go to escrow.
Agent submits shipping address via POST /v1/transactions/:id/shipping.
You receive the shipping address (via webhook or by polling).
Ship the order and update tracking via PATCH /v1/transactions/:id/shipping with trackingNumber, carrier, and shippingStatus: "shipped".
When delivered, set shippingStatus: "delivered". The transaction auto-fulfills and escrow releases.

Fulfillment & escrow release

For digital goods (APIs, datasets, models): once the agent receives the endpointUrl and calls your service, you can confirm delivery by calling:

POST /v1/transactions/:id/fulfill
Authorization: Bearer YOUR_AUTH_TOKEN

This marks the transaction as fulfilled and queues the escrow release.

If you don't call /fulfill, escrow releases automatically after the autoReleaseHours window from the product's SLA config (default: 24 hours).

Setting up SLA & auto-release

Define service level agreements for your products:

POST /v1/products/YOUR_PRODUCT_ID/sla
Authorization: Bearer YOUR_AUTH_TOKEN
Content-Type: application/json

{
  "responseTimeMs": 500,     // target: <500ms per call
  "uptimePct": 99.9,         // target: 99.9% uptime
  "autoReleaseHours": 2      // escrow auto-releases 2 hours after purchase
}

The autoReleaseHours is the most important field — it determines how quickly you receive payment if you don't manually call /fulfill.

To process auto-releases, run the cron script every few minutes:

# Add to cron / Railway cron job:
npx tsx src/scripts/process-escrow-releases.ts

Webhooks — get notified of purchases

Subscribe to purchase.created to receive an HTTP POST whenever an agent buys one of your products:

curl -X POST https://api.epanya.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sellerId": "YOUR_SELLER_ID",
    "url": "https://your-server.com/webhooks/epanya",
    "events": ["purchase.created"],
    "secret": "your-random-secret-string"
  }'

Verify the signature on your server:

const crypto = require("crypto");

function verifyWebhook(secret, body, sigHeader) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(sigHeader),
    Buffer.from(expected)
  );
}

Analytics

Track revenue, top products, and buyer behavior:

curl "https://api.epanya.ai/v1/sellers/YOUR_SELLER_ID/analytics?period=30d" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Or use the Analytics page in the seller dashboard at app.epanya.ai for a visual breakdown.

Using the Seller Dashboard

The Seller Dashboard at app.epanya.ai provides a web UI for:

Signing in with your wallet via SIWE (no password required)
Creating and editing product listings
Viewing sales count and seller rating
Revenue analytics with bar charts and top products

To run the dashboard locally for development:

cd seller-dashboard
npm install
npm run dev  # starts on http://localhost:3001

Wallet address: The wallet address you register with is where USDC payments are sent. Ensure it is a valid Base address and you have access to the private key. Epanya cannot recover funds sent to a wrong address.