> ## Documentation Index > Fetch the complete documentation index at: https://agora402.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Agora402 Shared Types and Utility Functions Reference > Reference for Agora402 shared TypeScript types: ServiceListing, Quote, Receipt, PricingModel, and utility functions priceFor, generateUaid, formatAmount. The `@agora402/shared` package is the single source of truth for every data structure and utility function that crosses the boundary between buyers, sellers, and the registry. All types come with runtime validation and full TypeScript inference from the same definition. The utility functions handle pricing arithmetic, amount formatting, UAID generation, and token estimation — all without floating-point arithmetic touching money. ## Installation and Import ```typescript theme={"system"} import { ServiceListing, Quote, Receipt, PricingModel, priceFor, generateUaid, formatAmount, } from '@agora402/shared'; ``` ## Types ### `ServiceListing` The record a seller publishes to the HCS registry topic. One listing describes an entire service: who receives payments, where the service lives, and which endpoints it sells. The seller's HCS-14 Universal Agent Identifier, always starting with `'uaid:'`. Generated with `generateUaid()`. Used as the primary key across the registry and receipt ledger. Human-readable service name, e.g. `'Hedera AI Seller'`. Semantic version string for the service, e.g. `'1.0.0'`. The Hedera account ID (`shard.realm.num`) that receives all payments. Must match the HCS message payer for the listing to be considered valid. The HTTPS base URL of the seller's service, e.g. `'https://seller.example.com'`. All endpoint paths are relative to this URL. Path of the quote endpoint relative to `baseUrl`. Defaults to `'/a2a/quote'`. URL of the x402 facilitator / Blocky402 instance that settles payments for this seller. One or more endpoints the service sells. See `EndpointSpec` below. Optional HCS topic ID where the seller writes `Receipt` messages after each settlement. Provide this so buyers can audit the billing trail independently. ISO 8601 timestamp at which the listing was created. *** ### `EndpointSpec` Describes a single sellable HTTP endpoint within a `ServiceListing`. Stable identifier for this endpoint within the service, e.g. `'infer'` or `'hbar-rate'`. Buyers use this to discover the service via `findEndpoint()` and `discover()`. HTTP method for this endpoint. URL path relative to `ServiceListing.baseUrl`, always starting with `'/'`, e.g. `'/a2a/infer'`. Human-readable description of what the endpoint does. HCS-14 / OASF skill code integers. Used for capability discovery in agent networks. Defaults to `[]`. One or more payment options for this endpoint. At least one entry is required. Buyers filter by `asset` and `network` to find compatible options. *** ### `PaymentOptionSpec` One way to pay for an endpoint — a specific combination of network, asset, and pricing model. The CAIP-2 network identifier for this payment option. Asset ID (`shard.realm.num`). `'0.0.0'` for native HBAR; an HTS token ID for token payments. Human-readable symbol for the asset, e.g. `'HBAR'` or `'TOLL'`. Decimal places for the asset. `8` for HBAR (1 HBAR = 100,000,000 tinybars). The pricing model for this payment option. See `PricingModel` below. *** ### `PricingModel` A discriminated union of three pricing strategies. All monetary amounts are stored as decimal strings to prevent floating-point precision loss. Charge a fixed amount per request, regardless of input size. ```typescript theme={"system"} const model: PricingModel = { kind: 'flat', amount: '1000000', // 0.01 HBAR }; ``` Discriminant. Always `'flat'`. Fixed price in atomic units, as a decimal integer string. Charge a base fee plus per-token costs for input and output. Used for LLM inference endpoints. ```typescript theme={"system"} const model: PricingModel = { kind: 'per-token', base: '500000', // 0.005 HBAR base inputPer1k: '100000', // 0.001 HBAR per 1k input tokens outputPer1k: '200000',// 0.002 HBAR per 1k output tokens }; ``` Discriminant. Always `'per-token'`. Flat fee charged once per request, regardless of token count. Cost per 1,000 input tokens in atomic units. Cost per 1,000 output tokens (budgeted from `max_tokens`) in atomic units. Charge a fixed amount per abstract unit — queries, seconds, kilobytes, or any other countable resource. ```typescript theme={"system"} const model: PricingModel = { kind: 'per-unit', unit: 'query', amountPerUnit: '2000000', // 0.02 HBAR per query }; ``` Discriminant. Always `'per-unit'`. Human-readable unit label, e.g. `'query'`, `'second'`, `'kb'`. Cost per one unit in atomic units, as a decimal integer string. *** ### `QuoteRequest` Sent by a buyer to the seller's `/a2a/quote` endpoint to request a price for a specific amount of work. Optional UAID of the requesting agent. Informational only — the seller does not enforce this. The endpoint the buyer wants to use, e.g. `'infer'`. The buyer's work estimate. Fields: `inputTokens` (integer), `maxOutputTokens` (integer), `units` (integer). All optional; the seller uses whichever fields are relevant to its pricing model. Defaults to `{}`. Optional ceiling price the buyer is willing to pay, in atomic units as a decimal string. The seller may accept this counter, reject it (HTTP 409), or quote between the counter and list price. Asset ID for the desired payment method. Defaults to `'0.0.0'` (HBAR). *** ### `Quote` Returned by the seller in response to a `QuoteRequest`. The seller signs the quote so the buyer can verify it was not tampered with in transit. Unique identifier for this quote (minimum 8 characters). The buyer includes this in the subsequent paid request so the seller can match the agreed price. The seller's UAID. Buyers verify this matches the listing's `uaid` to prevent quote substitution. The endpoint this quote covers. The CAIP-2 network for settlement. The asset to pay in. The agreed price in atomic units, as a decimal string. Unix timestamp (seconds) after which this quote is no longer valid. Typical validity window is 60–300 seconds. The work estimate and pricing inputs the seller used to compute `amount`, echoed back for auditability. Hex-encoded ECDSA or ED25519 signature over the canonical quote body, produced by the seller's account key. Hex-encoded DER public key corresponding to `signature`. When `verifyQuoteSigner` is enabled on the buyer, this key is verified against the seller's `payTo` account on the mirror node. *** ### `Receipt` Written to the receipts HCS topic by the seller after every successful payment settlement. See the [ReceiptLedger reference](/api/receipt-ledger) for how to read and audit receipts. Schema version. Always `1`. Message type discriminant. Always `'receipt'`. The seller's UAID. Hedera transaction ID of the settlement, e.g. `'0.0.12345@1700000000.123456789'`. CAIP-2 network where the payment was settled. Account ID of the buyer. Account ID of the seller's receiving account. Asset used for payment. Amount paid in atomic units. Endpoint path that was paid for. Optional. Quote ID from the negotiation, if a quote was used. Metering evidence from the seller, e.g. token counts. Optional SHA-256 hex digest of the response body. ISO 8601 timestamp when the seller generated the receipt. ## Utility Functions ### `priceFor(model, estimate)` ```typescript theme={"system"} priceFor(model: PricingModel, estimate?: WorkEstimate): bigint ``` Computes the price of a request in atomic units using the given pricing model and work estimate. All arithmetic uses `BigInt` — tinybars never pass through a float. Token costs are rounded up per 1,000-token block. ```typescript theme={"system"} // Flat pricing: always returns model.amount priceFor({ kind: 'flat', amount: '1000000' }) // → 1_000_000n // Per-token pricing priceFor( { kind: 'per-token', base: '500000', inputPer1k: '100000', outputPer1k: '200000' }, { inputTokens: 120, maxOutputTokens: 256 } ) // base + ceil(120/1000)*100000 + ceil(256/1000)*200000 // → 500000n + 100000n + 200000n = 800000n (all rounded up) // Per-unit pricing priceFor( { kind: 'per-unit', unit: 'query', amountPerUnit: '2000000' }, { units: 3 } ) // → 6_000_000n ``` Both buyers and sellers call `priceFor()` with the same pricing model and the same estimate. This reproducibility is what makes the quote handshake trustworthy: neither side can unilaterally inflate the price. *** ### `generateUaid(input)` ```typescript theme={"system"} generateUaid(input: AgentIdentityInput): string // Returns: 'uaid:aid:;uid=...;registry=...;proto=...;nativeId=...' ``` Generates a deterministic HCS-14 Universal Agent Identifier from the agent's identity fields. The core `aid` component is `Base58(SHA-384(canonical JSON))`, so the same identity always produces the same UAID and the identifier is collision-resistant. ```typescript theme={"system"} const uaid = generateUaid({ registry: 'agora402', name: 'my-buyer', version: '1.0.0', protocol: 'a2a', nativeId: 'hedera:testnet:0.0.12345', skills: [], uid: 'my-buyer', }); // → 'uaid:aid:3vQB5...;uid=my-buyer;registry=agora402;proto=a2a;nativeId=hedera:testnet:0.0.12345' ``` Registry namespace in lowercase, e.g. `'agora402'`. Use `'self'` when no registry applies. Display name for the agent. Semantic version string. Protocol identifier in lowercase, e.g. `'a2a'`, `'hcs-10'`, `'mcp'`. CAIP-10 style native identifier, e.g. `'hedera:testnet:0.0.12345'`. OASF / HCS-14 skill codes. Defaults to `[]`. Sorted before hashing so order does not affect the UAID. Registry-scoped unique identifier. Defaults to `'0'`. Optional A2A domain. Appended to the UAID as `domain=...` when provided. *** ### `formatAmount(amount, decimals, symbol)` ```typescript theme={"system"} formatAmount(amount: bigint | string, decimals: number, symbol: string): string ``` Converts an atomic-unit amount into a human-readable string without floating-point arithmetic. ```typescript theme={"system"} formatAmount(100_000_000n, 8, 'HBAR') // → '1 HBAR' formatAmount(50_000_000n, 8, 'HBAR') // → '0.5 HBAR' formatAmount(1_234_567n, 8, 'HBAR') // → '0.01234567 HBAR' formatAmount(500n, 6, 'TOLL') // → '0.0005 TOLL' ``` *** ### `parseAmount(human, decimals)` ```typescript theme={"system"} parseAmount(human: string, decimals: number): bigint ``` Parses a human-readable decimal string into atomic units. The inverse of `formatAmount()`. Uses only integer arithmetic — no floats. ```typescript theme={"system"} parseAmount('0.05', 8) // → 5_000_000n parseAmount('1', 8) // → 100_000_000n parseAmount('0.5', 6) // → 500_000n ``` `parseAmount()` silently truncates fractional digits beyond `decimals`. For example, `parseAmount('0.123456789', 8)` returns `12_345_678n`, discarding the ninth decimal digit. Always validate user-supplied amounts before passing them to this function. *** ### `estimateChatInput(body)` ```typescript theme={"system"} estimateChatInput(body: unknown): { inputTokens: number; maxOutputTokens: number } ``` Produces a deterministic work estimate from an OpenAI-style chat completion request body. Uses a simple `ceil(characters / 4)` heuristic (\~4 characters per token for English text). Both buyers and sellers call this function so the estimate is consistent across both sides of the price negotiation. ```typescript theme={"system"} const estimate = estimateChatInput({ messages: [ { role: 'user', content: 'Explain x402 in one sentence.' }, ], max_tokens: 256, }); // → { inputTokens: 8, maxOutputTokens: 256 } ``` An OpenAI-style request body. The function reads `body.messages[].content` (string or JSON-serialisable) and `body.prompt` (string fallback). `body.max_tokens` sets `maxOutputTokens`; defaults to `256` if absent or non-positive. Pass the same `body` object to both `estimateChatInput()` and the paid `call()` to ensure the estimate used for quoting matches the actual request, giving you predictable pricing.