x402 catalog #226 — Embedding Generation API bounty spec

gist_226_embeddings.md

[x402 catalog #226] Embedding Generation API

Bounty: $5 USDC on 0xWork. The real reward is owning the deployed API forever — every x402 agent calling it pays YOUR wallet on Base mainnet.

---

Problem

Embeddings are the backbone of RAG. Every retrieval step burns one. High call volume per agent, low per-call price → compounding revenue.

Endpoints

1. Embed text — {text, model} → {vector: [float], dimension, model_used, token_count}. Vectors must be real floats from a real model, not random.

2. Bulk embed — {texts: [string], model} → {vectors: [[float]], token_counts: [int], total_tokens}. Accept at least 100 texts per call.

3. Multi-model — {text, models: [string]} → {results: [{model, vector, dimension}]}.

4. Similarity — {text_a, text_b, model} → {cosine_similarity: float, dimension}.

5. Models — → {models: [{name, dimension, max_input_tokens, languages, price_per_1k_tokens}]}.

Data Source

• Reseller: OpenAI (text-embedding-3-*), Cohere (embed-v3), Voyage, Jina, Mistral embed. Wrap their API, charge a markup.
• Self-host: sentence-transformers (MiniLM, MPNet, BGE) on CPU or small GPU.

Endpoint-Specific Acceptance

• Same text + same model → same vector (deterministic or seeded)
• Different text → meaningfully different vectors (cosine similarity between unrelated sentences < 0.7)
• Cosine similarity between 'king' and 'queen' > 'king' and 'banana'
• Dimensions match model spec
• Multi-model returns different vectors per model
• At least 3 models available
• Bulk endpoint handles 100 inputs without timeout

Suggested Pricing

• Embed / bulk embed: $0.003-$0.01 per 1k tokens (above upstream cost)
• Multi-model: $0.005-$0.02 per 1k tokens
• Similarity: $0.003-$0.01
• Models list: $0.003-$0.005

---

Why Build This

The $5 bounty is setup money. The real reward: you OWN the deployed API. Every x402 agent that hits your endpoint pays YOUR wallet in USDC on Base mainnet. No intermediary. No revenue share with us. Pay-skill runs the discovery layer + facilitator; you run the service and keep 100% of the per-call stream. Reseller-friendly: wrap any upstream data source/model; the x402 interface IS the value-add.

NO FAKE DATA

Reviewers will call every endpoint with multiple real inputs. Different inputs must produce different, correct outputs. Static responses, lorem-ipsum, randomized fake values, or endpoints that ignore inputs will be rejected immediately.

Acceptance (all must pass)

1. Network: Base mainnet (chain 8453). NOT testnet, NOT another chain.
2. HTTPS endpoint. No HTTP, no IP literal, no localhost.
3. A successful x402 round-trip: unpaid request returns HTTP 402 with valid x402 headers (scheme, network, amount, payTo, settlement, facilitator). After payment, returns HTTP 200 with REAL data.
4. settlement: "tab" on every paid route. (NOT direct — micropayments. Direct settlement requires $1+ per call which doesn't fit this catalog's pricing.)
5. pay discover <keyword> finds the API. Heartbeat configured with name, description, keywords, category.
6. Each endpoint has a filled info block (Bazaar extension) with real example inputs + outputs. No "string" placeholders, no TODO.
7. Endpoint-specific acceptance criteria above all pass.
8. Stays live during the 48h verification window after submission.
9. No catalog disqualifiers: same response for all inputs, requires auth beyond x402, illegal/harmful content, duplicate of another submission.

Reference Tab-Settlement YAML Snippet

listen: ":8402"
proxy:
  target: "http://localhost:8080"
facilitator: "https://pay-skill.com/x402"
routes:
  - path: "/embed"
    price: "0.005"
    settlement: "tab"             # <-- required
    description: "Generate text embedding"
    info:
      input:
        type: "http"
        method: "POST"
        body:
          text: { type: "string", description: "Text to embed" }
          model: { type: "string", description: "Model id" }
      output:
        type: "json"
        example:
          vector: [0.123, -0.456, 0.789]
          dimension: 1536
          model_used: "text-embedding-3-small"
          token_count: 12
discovery:
  discoverable: true
  base_url: "https://your-api.example.com"
  name: "Your Embedding API"
  description: "OpenAI-compatible embeddings via x402"
  keywords: ["embeddings", "rag", "vector", "ai"]
  category: "ai-inference"

Proof of Work (include in submission)

1. Public HTTPS URL of your API
2. Your Base mainnet wallet address (where per-call USDC lands)
3. ONE successful round-trip showing 402 → payment → 200 with real data. Use whatever invocation makes sense (pay request works like curl). Paste the command + the response.

Build References

Choose your integration approach (pay-gate sidecar OR app middleware):

• pay-gate install + quickstart: https://pay-skill.com/docs/gate/quickstart
• pay-gate config (YAML, info blocks): https://pay-skill.com/docs/gate/config
• pay-gate full guide: https://pay-skill.com/docs/gate/guide
• App middleware (Express/Next/FastAPI): https://pay-skill.com/docs/middleware/
• Examples repo (16 patterns): https://github.com/pay-skill/pay-examples

Design + verification:

• API design best practices: https://pay-skill.com/docs/api-design
• Provider guide: https://pay-skill.com/docs/provider-guide
• Discovery + heartbeat: https://pay-skill.com/docs/api-reference
• Webhooks: https://pay-skill.com/docs/webhooks
• Catalog acceptance rules: https://pay-skill.com/docs/earn