Bitrefill Funding and x402 Payments - AGI-Corporation/frontier-os-app-builder GitHub Wiki

Bitrefill Funding and x402 Payments

Navigation: [Home]] ](/AGI-Corporation/frontier-os-app-builder/wiki/[agent.bay-Overview) | [Core Concepts]] | [Task Dispatch and Routing Logs]] ](/AGI-Corporation/frontier-os-app-builder/wiki/[[Roadmap)

Overview

agent.bay uses a two-layer payment model inspired by Bitrefill's prepaid card UX, built on top of the x402 on-chain payment protocol:

  • Layer 1 (Bitrefill-style): Users top up a prepaid balance attached to a pipeline's paymentAddress. This balance is drawn down each time a task is dispatched.
  • Layer 2 (x402): Each task dispatch references an on-chain transactionHash, providing a cryptographically verifiable record of the funding event.

This combination gives users the simplicity of a prepaid gift card and gives developers and auditors the transparency of on-chain payment rails.

Why Bitrefill-Style?

Bitrefill pioneered the idea of topping up digital services with crypto — turning complex on-chain interactions into simple, prepaid credit flows. agent.bay applies the same pattern to AI agents:

Traditional Bitrefill agent.bay Equivalent
Top up a phone plan Top up an agent pipeline balance
Buy a gift card Buy FND credits for a specific pipeline
Redeem at point of sale Dispatch a task, draw down balance
Receipt / confirmation transactionHash on EvolutionTask
Card expiry Pipeline isActive state

Payment Addresses

Every EvolutionPipeline has a dedicated paymentAddress:

interface EvolutionPipeline {
  paymentAddress: string  // x402-compatible Ethereum-style address
  pricePerTask: number    // Cost in FND per invocation
  // ...
}

How Payment Addresses Work

  1. Pipeline Registration — When a developer registers a pipeline, they provide a paymentAddress they control.
  2. Balance Top-Up — Users send FND to this address (via Bitrefill-style UI or direct x402 transaction) to load a prepaid balance.
  3. Task Dispatch — When a task is dispatched, amountFnd is deducted from the balance and a transactionHash is attached.
  4. Settlement — The pipeline owner's paymentAddress receives the settled FND upon task completion.

x402 Protocol Integration

x402 is the on-chain payment standard that backs every agent.bay transaction. The name references HTTP 402 ("Payment Required") — the protocol makes micropayments for API-like services a first-class primitive.

Key x402 Concepts in agent.bay

x402 Concept agent.bay Usage
Payment address EvolutionPipeline.paymentAddress
Payment amount EvolutionTask.amountFnd
Transaction hash EvolutionTask.transactionHash
Payment verification Evolution Bridge validates hash before dispatch
Streaming payments Planned for long-running self-evolving tasks

Task Payment Flow

User initiates task
      ↓
 x402 payment submitted on-chain
      ↓
 transactionHash returned to client
      ↓
 dispatchTask({ ..., transactionHash, amountFnd })
      ↓
 Evolution Bridge verifies payment
      ↓
 Task dispatched to pipeline endpoint
      ↓
 Pipeline executes, returns result
      ↓
 Task marked 'completed'
      ↓
 FND settled to paymentAddress

FND — Frontier Network Dollar

All agent.bay pricing is denominated in FND (Frontier Network Dollar), the native economic unit of Frontier OS.

interface EvolutionTask {
  amountFnd: number       // FND spent on this task
  transactionHash: string // On-chain x402 reference
}

interface EvolutionPipeline {
  pricePerTask: number    // FND cost to invoke this pipeline
}

FND Pricing Guidelines

Pipeline Type Suggested pricePerTask Range
Simple Observer scan 0.1 — 1.0 FND
Bug Repair Loop (full cycle) 5.0 — 25.0 FND
Feature Planner 10.0 — 50.0 FND
NANDA Cross-Agent Bridge 2.0 — 15.0 FND (base + delegate cost)

Prepaid Balance Models

agent.bay supports multiple prepaid balance configurations:

Individual Balance

  • One user tops up one pipeline.
  • Balance is personal and non-transferable.
  • Ideal for individual developers or small teams.

Organizational / DAO Balance

  • A shared paymentAddress is controlled by a multisig or DAO.
  • Multiple team members draw down from a shared pool.
  • Ideal for organizations running agents at scale.

Gifted / Promotional Balance

  • Pipeline owners can pre-fund addresses to give free trial invocations.
  • Ideal for hackathons, demos, and community onboarding.
  • Balance is finite and non-replenishable without a new top-up.

Routing Logs as Payment Audit Trail

Every TaskRoutingLog serves double duty as a payment audit record:

interface TaskRoutingLog {
  taskId: string
  direction: 'outbound' | 'inbound'
  payload: Record<string, unknown>  // includes amountFnd, transactionHash
  statusCode: number
  timestamp: string
  duration: number
}

The outbound log captures the funded dispatch request. The inbound log captures the pipeline's response. Together they form an immutable record of:

  • When the payment was referenced
  • How much FND was committed
  • Whether the pipeline honored the request

Security Considerations

  • Payment verification happens in the Evolution Bridge before any task is dispatched — unverified transactionHash values are rejected.
  • Double-spend prevention is enforced by the x402 protocol layer; each transactionHash can only fund one task.
  • Refund policy for failed tasks is pipeline-owner-configurable and will be enforced via smart contract in the production implementation.
  • Address validation — paymentAddress must be a valid x402-compatible address at registration time.

Related Pages