Developer quickstart

Build your first paid agent flow on Ergo.

This is the shortest honest path from a web app to Sage: quote a premium task, hand a structured intent to your wallet layer, verify the testnet Note, then fetch the machine-readable receipt bundle.

Open widget demo Wallet runner Policy playground Package source

Testnet first

The live flow is useful because it is inspectable. It is not audited mainnet infrastructure. Keep real funds out of this path until the mainnet gate is explicitly opened.

Install the widget

Use the npm package for React, vanilla DOM, typed API clients, and receipt helpers.

Ask for a quote

Premium-shaped requests return price, task hash, receiver, reserve, expiry, and deadline.

Hand intent to wallet

The package emits a portable payment intent. Your app owns wallet policy and signing.

Verify and fetch receipt

Sage verifies the Note box id, streams the answer, and publishes the receipt bundle.

Copy-paste path

Start with the widget. Drop lower only when you need custom UX.

The React widget is the fastest surface for product teams. The typed API clients are for wallets, agents, and custom developer tools that need to own every screen and log line.

Install

npm install @ergoblockchain/sage-widget

React paid widget

import { SagePaymentWidget } from "@ergoblockchain/sage-widget/react"

export function PaidAgentPanel() {
  return (
    <SagePaymentWidget
      tenant={{ id: "my-agent-app", label: "My Agent App" }}
      paymentInstructions={{
        helperText: "Create the quoted Ergo testnet Note, then paste the Note box id.",
        walletLauncherLabel: "Open my testnet wallet",
      }}
      onPaymentIntent={(intent) => console.log("wallet intent", intent)}
      onReceipt={(receipt) => console.log("receipt", receipt.receiptUrl)}
      onReceiptBundle={(bundle) => console.log(bundle.completeness)}
      walletLauncher={async (intent) => {
        // Your app owns policy, wallet UI, ErgoPay/Fleet integration and signing.
        // Return { ok: true, noteBoxId } after creating the testnet Note.
        console.log(intent.amountErg, intent.receiverAddress, intent.taskHash)
        return { ok: true }
      }}
    />
  )
}

Typed API flow

import {
  fetchSageQuote,
  createSagePaymentIntent,
  verifySagePayment,
  fetchSageReceipt,
} from "@ergoblockchain/sage-widget"

const question = "/deep explain Accord receipts"
const quote = await fetchSageQuote({ question })
if (!quote.quote) throw new Error("No premium quote returned")

const intent = createSagePaymentIntent({
  question,
  quote: quote.quote,
  tenant: { id: "my-agent-app", label: "My Agent App" },
})

// Give intent to your wallet layer. It creates an Ergo testnet Note.
const noteBoxId = await createNoteWithYourWallet(intent)

const verified = await verifySagePayment({
  quote: quote.quote,
  question,
  noteBoxId,
})

const receipt = await fetchSageReceipt(verified.receiptId)
console.log(receipt.completeness)

Payment intent shape

{
  "type": "sage.payment_intent.v1",
  "network": "ergo-testnet",
  "amountErg": "0.001",
  "receiverAddress": "...",
  "reserveBoxId": "...",
  "taskHash": "...",
  "verifyEndpoint": "https://www.ergoblockchain.org/api/sage/verify-payment",
  "receiptEndpointTemplate": "https://www.ergoblockchain.org/api/sage/receipt/{receiptId}"
}

Operating rules

Keep the proof surface boring where it matters.

Rule 1

Use testnet only until external review and audit-bound mainnet script identity are published.

Rule 2

Do not let the widget sign funds. Keep custody and wallet policy in the host app.

Rule 3

Treat /api/sage/receipt/<id> as the source of truth. Pages and widgets should display or link to it.

Rule 4

Log payment intent, verification result, receipt URL, and receipt completeness in your own telemetry.

Receipt API is the truth

After verification, link to the public receipt page for humans and store the API receipt URL for machines. The receipt bundle is where Agreement JSON, Verification Receipt JSON, and Settlement Receipt JSON belong.

Inspect latest bundle

Next after the quickstart

Turn this into a wallet-specific integration: policy limits, ErgoPay or Fleet construction, local signing, transaction simulation, Note box discovery, verification, and receipt storage in your own app.

View Live Hub