@aweto-agent/core

@aweto-agent/core is the core runtime for building AI agents with typed entrypoints, discovery endpoints, monetization hooks, and trust metadata. It provides the shared runtime logic used by adapter packages like @aweto-agent/hono and @aweto-agent/tanstack.

Note: For most use cases, you'll want to use one of the adapter packages (@aweto-agent/hono or @aweto-agent/tanstack) rather than importing from this core package directly.

Highlights

• Type-safe entrypoints with optional Zod input and output schemas.
• Automatic /health, /entrypoints, and AgentCard manifest routes.
• Built-in Server-Sent Events (SSE) streaming helpers.
• Optional x402 monetization and per-entrypoint pricing/network overrides.
• Shared runtime configuration with environment + runtime overrides.
• ERC-8004 trust and AP2 manifest integration out of the box.
• Utilities for x402-enabled LLM calls, agent wallets, and identity registries.

Install & Import

This is the core runtime package. For building agents, use one of the adapter packages:

Hono Adapter:

import { createAgentApp } from '@aweto-agent/hono';
import type { EntrypointDef, AgentMeta } from '@aweto-agent/core';

Express Adapter:

import { createAgentApp } from '@aweto-agent/express';
import type { EntrypointDef, AgentMeta } from '@aweto-agent/core';

TanStack Adapter:

import { createTanStackRuntime } from '@aweto-agent/tanstack';
import type { EntrypointDef, AgentMeta } from '@aweto-agent/core';

Subpath exports (shared across adapters):

• @aweto-agent/core — main exports including types (EntrypointDef, AgentMeta, etc.)
• @aweto-agent/core/utils — focused helpers (toJsonSchemaOrUndefined, etc.)
• @aweto-agent/core/axllm — AxLLM client integration

Core Concepts

Core Runtime

This package provides the core runtime logic. Adapter packages like @aweto-agent/hono and @aweto-agent/tanstack wrap this runtime with framework-specific implementations.

The runtime manages:

• meta (AgentMeta) shapes the health check and manifest.
• options.config applies runtime overrides for payments and wallet defaults. These overrides merge with environment variables and package defaults via getAgentKitConfig.
• options.payments sets payment configuration for entrypoints. Pass false to explicitly disable paywalling. If omitted and not disabled, entrypoints without explicit prices won't require payment.
• options.ap2 promotes an Agent Payments Protocol extension entry into the manifest.
• options.trust pushes ERC-8004 trust metadata into the manifest.
• options.entrypoints pre-registers entrypoints without additional calls.

The return value exposes:

• app — the underlying server instance (Hono or Express) you can serve with Bun/Node platforms.
• addEntrypoint(def) — register more entrypoints at runtime.
• config — the resolved AgentKitConfig after env and runtime overrides.
• payments — the active PaymentsConfig (if paywalling is enabled) or undefined.

Example with Hono Adapter:

import { z } from 'zod';
import { createAgentApp } from '@aweto-agent/hono';

const { app, addEntrypoint } = createAgentApp({
  name: 'hello-agent',
  version: '0.1.0',
  description: 'Echoes whatever you pass in',
});

addEntrypoint({
  key: 'echo',
  description: 'Echo a message',
  input: z.object({ text: z.string() }),
  async handler({ input }) {
    return {
      output: { text: String(input.text ?? '') },
      usage: { total_tokens: String(input.text ?? '').length },
    };
  },
});

export default app;

Example with Express Adapter:

import { z } from 'zod';
import { createAgentApp } from '@aweto-agent/express';

const { app, addEntrypoint } = createAgentApp({
  name: 'hello-agent',
  version: '0.1.0',
  description: 'Echoes whatever you pass in',
});

addEntrypoint({
  key: 'echo',
  description: 'Echo a message',
  input: z.object({ text: z.string() }),
  async handler({ input }) {
    return {
      output: { text: String(input.text ?? '') },
      usage: { total_tokens: String(input.text ?? '').length },
    };
  },
});

app.listen(process.env.PORT ?? 3000);

Example with TanStack Adapter:

import { z } from 'zod';
import { createTanStackRuntime } from '@aweto-agent/tanstack';

const { runtime, handlers } = createTanStackRuntime({
  name: 'hello-agent',
  version: '0.1.0',
  description: 'Echoes whatever you pass in',
});

runtime.entrypoints.add({
  key: 'echo',
  description: 'Echo a message',
  input: z.object({ text: z.string() }),
  async handler({ input }) {
    return {
      output: { text: String(input.text ?? '') },
      usage: { total_tokens: String(input.text ?? '').length },
    };
  },
});

const { agent } = runtime;
export { agent, handlers, runtime };

Supported Networks

Lucid-agents supports payment receiving on multiple blockchain networks:

EVM Networks

• base - Base mainnet (L2)
• base-sepolia - Base Sepolia testnet
• ethereum - Ethereum mainnet
• sepolia - Ethereum Sepolia testnet

Solana Networks

• solana - Solana mainnet
• solana-devnet - Solana devnet

Address Formats

• EVM: 0x-prefixed hex (42 characters) - e.g., 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0
• Solana: Base58 encoding (~44 characters, no prefix) - e.g., 9yPGxVrYi7C5JLMGjEZhK8qQ4tn7SzMWwQHvz3vGJCKz

Example with Solana

const { app, addEntrypoint } = createAgentApp(
  {
    name: 'solana-agent',
    version: '1.0.0',
    description: 'Agent accepting Solana USDC payments',
  },
  {
    payments: {
      payTo: '9yPGxVrYi7C5JLMGjEZhK8qQ4tn7SzMWwQHvz3vGJCKz', // Solana address
      network: 'solana-devnet',
      facilitatorUrl: 'https://facilitator.world.fun/',
    },
  }
);

addEntrypoint({
  key: 'translate',
  description: 'Translate text',
  input: z.object({ text: z.string(), target: z.string() }),
  async handler({ input }) {
    // Your translation logic
    return {
      output: { translated: `Translated: ${input.text}` },
    };
  },
});

SPL Token Addresses

For Solana payments, USDC addresses are:

• Mainnet USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
• Devnet USDC: Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr

Entrypoints

EntrypointDef describes a unit of work. Each entrypoint becomes two HTTP endpoints:

• POST /entrypoints/:key/invoke — always available; returns JSON { run_id, status, output?, usage?, model? }.
• POST /entrypoints/:key/stream — only registered when streaming and stream are provided; streams run-start, delta, text, asset, control, error, and run-end events over SSE.

Field highlights:

• input / output accept Zod schemas and automatically drive validation and manifest JSON schema generation.
• handler(ctx) handles non-streaming invocations.
• stream(ctx, emit) emits StreamPushEnvelopes and finishes with a StreamResult.
• price accepts either a single string or { invoke?, stream? }; network can override the global payment network per entrypoint.

addEntrypoint({
  key: 'stream',
  description: 'Streams characters back to the caller',
  input: z.object({ prompt: z.string() }),
  streaming: true,
  price: { stream: '2500' },
  async stream({ input }, emit) {
    for (const ch of input.prompt ?? '') {
      await emit({ kind: 'delta', delta: ch, mime: 'text/plain' });
    }
    return { output: { done: true } };
  },
});

HTTP routes

Every agent app exposes the following for free:

• GET /health → { ok: true, version }
• GET /entrypoints → { items: Array<{ key, description?, streaming }> }
• GET /.well-known/agent.json and /.well-known/agent-card.json → full manifest (skills, schemas, pricing, trust metadata, AP2 extension, etc.)
• POST /entrypoints/:key/invoke and (optional) POST /entrypoints/:key/stream as described above.
• GET / → lightweight HTML page that renders the manifest (handy for local inspection).

Configuration & Environment

core keeps configuration centralized so every helper resolves the same values.

• Defaults live in src/config.ts (currently empty placeholders).
• Environment variables flow in via the extension helpers (paymentsFromEnv() and walletsFromEnv()).
• configureAgentKit(overrides) merges values at runtime; use it inside tests or before calling createAgentApp.
• getAgentKitConfig() returns the resolved values; resetAgentKitConfigForTesting() clears overrides.

The helper paymentsFromEnv() returns the currently resolved PaymentsConfig, honouring inline config and environment values. walletsFromEnv() follows the same pattern.

import {
  configureAgentKit,
  getAgentKitConfig,
  paymentsFromEnv,
} from '@aweto-agent/core';

configureAgentKit({
  payments: {
    facilitatorUrl: 'https://facilitator.example',
    payTo: '0x...',
    network: 'base-sepolia',
  },
  wallets: {
    agent: {
      type: 'local',
      privateKey: '0xabc...',
    },
  },
});

const config = getAgentKitConfig();
console.log(config.payments?.facilitatorUrl); // resolved facilitator
console.log(config.wallets?.agent?.type); // 'local'
console.log(paymentsFromEnv()); // reuse inside handlers

Payments & Monetization

When a PaymentsConfig is active, createAgentApp automatically wraps invoke/stream routes with the x402-hono middleware via withPayments. Pricing:

• Each entrypoint must explicitly define its price (string or { invoke?, stream? } object)
• If no price is set, the entrypoint is free (no paywall)

resolvePrice(entrypoint, payments, kind) (from @aweto-agent/payments) returns the price or null.

For authenticated wallet access, pair your agent with @aweto-agent/agent-auth and reuse the generated SDK surface:

import { AgentRuntime } from '@aweto-agent/agent-auth';
import { createRuntimePaymentContext } from '@aweto-agent/payments';

const { runtime } = await AgentRuntime.load({
  wallet: {
    signer: {
      async signChallenge(challenge) {
        // sign however your environment requires
        return `signed:${challenge.id}`;
      },
    },
  },
  loader: {
    overrides: {
      baseUrl: process.env.LUCID_API_URL,
      agentRef: process.env.AGENT_REF,
      credentialId: process.env.CREDENTIAL_ID,
      scopes: ['agents.read'],
    },
  },
});

const token = await runtime.ensureAccessToken();
const agents = await runtime.api.listAgents();
console.log('active bearer token', token.slice(0, 12), agents.items.length);

// Wrap fetch with x402 payments using the runtime-managed wallet
const { fetchWithPayment } = await createRuntimePaymentContext({
  runtime,
});

const paidResponse = await fetchWithPayment?.('https://paid.endpoint/api', {
  method: 'POST',
  body: JSON.stringify({ prompt: 'charge me' }),
  headers: { 'content-type': 'application/json' },
});
console.log('paid response', await paidResponse?.json());

Manifest, AP2, and Discovery

buildManifest({ meta, registry, origin, payments, ap2, trust }) powers the well-known endpoints. It produces an A2A-compatible AgentCard that includes:

• skills[] mirroring entrypoints and their schemas.
• capabilities.streaming when any entrypoint offers SSE.
• payments[] with x402 metadata when monetization is active.
• AP2 extension entries when ap2 is supplied or when payments are enabled (defaults to a required merchant role).
• Trust metadata (registrations, trustModels, validation URIs) from TrustConfig.

The manifest is automatically generated by createAgentApp using the A2A protocol base card and enhancement functions for payments, identity, and AP2 extensions.

Trust & Identity (ERC-8004)

Trust metadata is modelled by TrustConfig. For ERC-8004 identity management, use the dedicated @aweto-agent/identity package:

import { createAgentIdentity, getTrustConfig } from '@aweto-agent/identity';

// Register agent identity with auto-registration
const identity = await createAgentIdentity({
  domain: 'agent.example.com',
  autoRegister: true,
  chainId: 84532,
  trustModels: ['feedback', 'inference-validation'],
});

// Use in your agent app
const { app } = createAgentApp(
  { name: 'my-agent', version: '1.0.0' },
  { trust: getTrustConfig(identity) }
);

console.log(`Agent ID: ${identity.record?.agentId}`);
console.log(`Status: ${identity.status}`);

The package also exports lower-level helpers for advanced use cases:

• createIdentityRegistryClient({ address, chainId, publicClient, walletClient }) — direct registry access for advanced workflows.
• signAgentDomainProof({ domain, address, chainId, signer }) — manually sign domain ownership proofs.
• buildTrustConfigFromIdentity(record, { signature, chainId, namespace, trustOverrides }) — convert registry records into TrustConfig.

See @aweto-agent/identity documentation for complete examples and API reference.

Agent-to-Agent (A2A) Client

Agents can call other agents using the A2A protocol. The A2A client is available through the runtime:

import { createRuntimePaymentContext } from '@aweto-agent/payments';

addEntrypoint({
  key: 'delegate',
  handler: async ctx => {
    const runtime = ctx.runtime;
    if (!runtime?.a2a) {
      throw new Error('A2A client not available');
    }

    // Create payment-enabled fetch (optional)
    const paymentContext = await createRuntimePaymentContext({
      runtime,
      network: 'base-sepolia',
    });

    // Fetch worker agent's card
    const workerCard = await runtime.a2a.fetchCard(
      'https://worker.example.com',
      paymentContext.fetchWithPayment
    );

    // Call worker agent
    const result = await runtime.a2a.client.invoke(
      workerCard,
      'process',
      ctx.input.data,
      paymentContext.fetchWithPayment
    );

    return { output: { result: result.output } };
  },
});

Convenience Functions

import { fetchAndInvoke } from '@aweto-agent/a2a';

// Fetch card and invoke in one call
const result = await fetchAndInvoke(
  'https://worker.example.com',
  'process',
  { data: [1, 2, 3] },
  fetchWithPayment // optional
);

See examples/full-agent.ts for a complete agent example, or use the trading-data-agent and trading-recommendation-agent CLI templates for A2A composition examples.

x402 + AxFlow utilities

For downstream components that need to call LLMs with paid fetches, the utils folder exposes:

• createX402Fetch({ account, fetchImpl }) and accountFromPrivateKey(privateKey) — wrap a fetch implementation with x402 payments.
• createX402LLM(options) — compose a paid fetch with @ax-llm/ax.
• createAxLLMClient({ provider, model, apiKey, temperature, x402, logger }) — ergonomic wrapper that reads env defaults (OPENAI_API_KEY, AX_*, AXLLM_*) and falls back to gpt-5/OpenAI. It returns { ax, isConfigured }.

Miscellaneous utilities

• toJsonSchemaOrUndefined(zodSchema) — safe JSON-schema conversion.
• normalizeAddress, sanitizeAddress, toCaip10 — address manipulation helpers used by the trust layer.
• defaults — exported constants describing the built-in facilitator URL, pay-to address, network, and API base URL.