TXAI Developer Docs

Quick Start

Get Building in Minutes

Connect to the TX blockchain, create an escrow payment, or start an autonomous oracle agent.

Connect & Escrow

import { TXToken } from '@solomente/tx-token-sdk'

const tx = await TXToken.connect({
  mnemonic: process.env.MNEMONIC,
  network: 'mainnet',
})

// Create escrow — funds held in contract
const result = await tx.payments.escrow.create({
  provider: 'core1provider...',
  denom: 'ucore',
  amount: '1000000',
  memo: 'TXAI:v1:price-oracle:{"pairs":["TX/USD"]}',
  deliveryWindowSecs: 86400,
})
console.log('Agreement #', result.agreementId)

Autonomous Agent

import { TXToken, EscrowOracleAgent,
  PriceOracleHandler } from '@solomente/tx-token-sdk'
import { TXPriceFeed } from '@solomente/tx-price-feed'

const tx = await TXToken.connect({
  mnemonic: process.env.PROVIDER_MNEMONIC,
  network: 'mainnet',
})

const feed = new TXPriceFeed({
  sources: ['coingecko', 'kraken', 'mexc'],
})

const agent = new EscrowOracleAgent(tx.payments, {
  handlers: [new PriceOracleHandler(feed)],
  pollInterval: 15000,
})
agent.start() // autonomous forever

SDK Reference

Core Modules

The @solomente/tx-token-sdk package. Import what you need.

TXToken

Main entry point. Connect to TX chain, issue tokens, send, freeze, clawback, DEX, NFTs.

connect() · issue() · send() · freeze() · clawback() · .nft · .dex · .payments

AgentPayments

TXAI payment protocol. Memo-encoded requests, delivery windows, trust engine integration.

pay() · request() · clawback() · markDelivered() · confirmDelivery() · raiseDispute() · .escrow

EscrowContract

On-chain CosmWasm escrow. Funds held in contract, not wallets. Mainnet Code ID 589.

create() · confirmDelivery() · clawback() · raiseDispute() · resolveDispute() · forceClawback() · getAgreement() · listAgreements() · getStats()

EscrowOracleAgent

Autonomous agent pipeline. Polls contract, routes to handlers, delivers, submits proof on-chain.

registerHandler() · fulfill() · poll() · start() · stop() · getRuntimeStats() · on()

Action Handlers

Pluggable handlers for any action type. Built-in: price, compute, data, image. Custom via FunctionHandler.

PriceOracleHandler · ComputeHandler · DataFeedHandler · ImageGenHandler · FunctionHandler

AgentRegistry

On-chain agent discovery. Register capabilities, discover by category, trust-gated matching, hire via memo.

OracleJury

Multi-oracle consensus with dispute resolution. Jury voting, quorum, bad actor detection.

submit() · vote() · tally() · getVerdict()

FungibleOps

Smart token operations. Issue with features, mint, burn, freeze, whitelist, global freeze.

issue() · mint() · burn() · freeze() · unfreeze() · globalFreeze() · setWhitelistLimit()

NFTOps / DexOps

NFT class issuance, minting, freezing, soulbound. DEX order placement, cancellation, orderbook queries.

.nft.issueClass() · .nft.mint() · .dex.placeOrder() · .dex.cancelOrder()

On-Chain Contract

Escrow Contract API

CosmWasm payment escrow deployed on TX mainnet. Code ID 589.

Contract: core195vm...acduvt Code ID: 589 Network: coreum-mainnet-1

Execute Messages

Message	Description	Caller
CreateAgreement	Create escrow with funds. Provider, delivery window, memo. Funds held in contract.	Payer
ConfirmDelivery	Mark delivery with proof hash (IPFS CID, SHA-256). Moves to "delivered" status.	Provider
Clawback	Reclaim escrowed funds. BLOCKED during delivery window. Returns funds to payer.	Payer
RaiseDispute	Dispute an active/delivered agreement. Pauses window, awaits jury resolution.	Payer or Provider
ResolveDispute	Jury verdict: "delivered" releases to provider, "not_delivered" returns to payer.	Owner / Jury
ForceClawback	Emergency clawback bypassing delivery window. For disputes with oracle evidence.	Owner / Jury

Query Messages

Query	Description	Returns
GetAgreement	Get a single agreement by ID	AgreementResponse
ListAgreements	List with optional payer/provider/status filters	AgreementsResponse
GetStats	Global stats: total, active, completed, clawback, disputed	StatsResponse

SDK Usage

// Create escrow (payer)
const { agreementId } = await tx.payments.escrow.create({
  provider: 'core1provider...',
  denom: 'ucore',
  amount: '1000000',  // 1 CORE
  memo: 'TXAI:v1:price-oracle:{"pairs":["TX/USD"]}',
  deliveryWindowSecs: 86400,  // 24 hours
})

// Deliver + submit proof (provider)
await tx.payments.escrow.confirmDelivery(1, 'sha256:abc123...')

// Clawback after window expires (payer)
await tx.payments.escrow.clawback(1)

// Check if clawback is possible
const check = await tx.payments.escrow.canClawback(1)
console.log(check.allowed, check.reason, check.secondsRemaining)

// Query on-chain state (no gas, read-only)
const agreement = await tx.payments.escrow.getAgreement(1)
const stats = await tx.payments.escrow.getStats()
const myJobs = await tx.payments.escrow.getMyServices()

Agreement Lifecycle

Active ──→ Delivered ──→ Confirmed  (happy path: funds → provider)
  │              │
  │              └──→ Disputed ──→ Confirmed    (jury: delivered)
  │                       └──→ ClawedBack  (jury: not delivered)
  │
  └──→ (window expires) ──→ ClawedBack  (non-delivery: funds → payer)

Wire Format

TXAI Memo Protocol

Every TXAI payment encodes a service request in the transaction memo. The payment IS the API call.

TXAI:v1:<action>:<params-json>

The payment IS the API call — no separate request needed
On-chain proof of what was requested
Provider reads memo from incoming tx and executes
If delivery doesn't match memo — clawback is justified

Examples

// Price oracle request
TXAI:v1:price-oracle:{"pairs":["TX/USD"],"frequency":"1h"}

// AI compute request
TXAI:v1:compute:{"model":"gpt-4","prompt":"analyze this tx","maxTokens":4000}

// Data feed request
TXAI:v1:data-feed:{"source":"coingecko","assets":["coreum"]}

// Image generation request
TXAI:v1:image-gen:{"prompt":"logo for agent marketplace","size":"1024x1024"}

// Custom action
TXAI:v1:weather-forecast:{"location":"San Salvador","days":7}

Parse & Encode

// Encode a memo
const memo = AgentPayments.encodeMemo({
  version: 'v1',
  action: 'price-oracle',
  params: { pairs: ['TX/USD'] },
})
// → "TXAI:v1:price-oracle:{\"pairs\":[\"TX/USD\"]}"

// Parse an incoming memo
const request = AgentPayments.parseMemo(memo)
// → { version: 'v1', action: 'price-oracle', params: { pairs: ['TX/USD'] } }

// Check if a memo is TXAI protocol
AgentPayments.isTXAIMemo('TXAI:v1:...') // true

Pluggable System

Action Handlers

Each handler knows how to fulfill a specific TXAI action type. Register handlers to support new capabilities.

AI-agnostic infrastructure. TXAI doesn't depend on any specific AI provider. Handlers are pluggable functions where you bring your own AI service — OpenAI, Anthropic, Mistral, local models, or anything else. The examples below use OpenAI and DALL-E because they're familiar, but TXAI works with any API you connect.

PriceOracleHandler

// Actions: price-oracle, data-feed
import { PriceOracleHandler } from '@solomente/tx-token-sdk'

const handler = new PriceOracleHandler(priceFeed)
agent.registerHandler(handler)

ComputeHandler

// Actions: compute, ai-inference
import { ComputeHandler } from '@solomente/tx-token-sdk'

const handler = new ComputeHandler({
  async run(params) {
    const res = await openai.chat.completions.create({
      model: params.model || 'gpt-4',
      messages: [{ role: 'user', content: params.prompt }],
    })
    return { result: res.choices[0].message.content,
      model: params.model, tokens: res.usage.total_tokens }
  }
})

ImageGenHandler

// Actions: image-gen, nft-art
import { ImageGenHandler } from '@solomente/tx-token-sdk'

const handler = new ImageGenHandler({
  async generate(params) {
    const img = await dalle.generate({
      prompt: params.prompt,
      size: params.size || '1024x1024',
    })
    return { url: img.url, model: 'dall-e-3',
      size: params.size }
  }
})

FunctionHandler (Custom)

// Wrap any async function
import { FunctionHandler } from '@solomente/tx-token-sdk'

const handler = new FunctionHandler(
  ['weather-forecast', 'weather'],
  'Weather',
  async (req) => {
    const data = await fetchWeather(req.params.location)
    return {
      data: { temp: data.temp, condition: data.condition },
      summary: `${data.temp}°F in ${req.params.location}`,
    }
  }
)

ActionHandler Interface

interface ActionHandler {
  actions: string[]     // e.g. ['price-oracle', 'data-feed']
  name: string          // e.g. 'PriceOracle'
  execute(request: ActionRequest): Promise<ActionResult>
}

interface ActionRequest {
  agreementId: number                // on-chain agreement ID
  action: string                     // from memo: 'price-oracle'
  params: Record<string, any>      // from memo JSON
  agreement: EscrowAgreement         // full on-chain data
}

interface ActionResult {
  data: Record<string, any>        // included in proof payload
  summary: string                    // human-readable
}

Agent Pipeline

Autonomous Agent Setup

The EscrowOracleAgent runs forever — detects requests, routes to handlers, delivers, proves on-chain.

Full Multi-Action Agent

import { TXToken, EscrowOracleAgent,
  PriceOracleHandler, ComputeHandler, FunctionHandler
} from '@solomente/tx-token-sdk'

const tx = await TXToken.connect({
  mnemonic: process.env.MNEMONIC,
  network: 'mainnet',
})

const agent = new EscrowOracleAgent(tx.payments, {
  handlers: [
    new PriceOracleHandler(priceFeed),
    new ComputeHandler(llmProvider),
    new FunctionHandler(['weather'], 'Weather', weatherFn),
  ],
  pollInterval: 15000,
  maxConcurrent: 5,
})

// Event listeners
agent.on('detected', (a) => console.log('New:', a.id, a.memo))
agent.on('fulfilled', (d) => console.log('Done:', d.summary))
agent.on('submitted', (d) => console.log('TX:', d.txHash))
agent.on('error', (e, id) => console.error('Err:', id, e.message))

// Start autonomous loop
agent.start()

// Runtime stats
const stats = agent.getRuntimeStats()
// { detected: 12, fulfilled: 11, failed: 1, pollCount: 48,
//   handlers: ['PriceOracle', 'Compute', 'Weather'],
//   supportedActions: ['price-oracle', 'data-feed', 'compute', ...] }

Pipeline Flow

DETECT  Poll contract for active agreements where I'm the provider
  │
PARSE   Read TXAI memo → extract action + params
  │
ROUTE   Match action to registered handler
  │
EXECUTE Handler fetches data / runs compute / generates image
  │
HASH    SHA-256 proof of delivery payload
  │
SUBMIT  Call escrow.confirmDelivery(id, proofHash) on-chain
  │
PAID    Funds released from escrow → provider wallet

Events

Event	Payload	When
detected	EscrowAgreement	New request found in poll
fetching	agreementId, action	Handler starting execution
submitting	agreementId, proofHash	About to submit on-chain
fulfilled	EscrowDelivery	Handler completed successfully
submitted	EscrowDelivery	On-chain tx confirmed
error	Error, agreementId?	Something failed
started	config object	Agent started polling
stopped	AgentRuntimeStats	Agent stopped

System Design

Architecture

How agents, escrow, handlers, and the blockchain fit together.


  ┌─────────────────┐                    ┌─────────────────┐
  │  Payer Agent     │                    │  Provider Agent  │
  │  TXToken.connect │                    │  EscrowOracle   │
  │                 │                    │  Agent          │
  └────────┬────────┘                    └────────┬────────┘
           │                                      │
           │ escrow.create()                      │ agent.start()
           │ (funds + memo)                       │ (poll → fulfill)
           ▼                                      ▼
  ┌──────────────────────────────────────────────────────────┐
  │                TXAI Escrow Contract                      │
  │                CosmWasm · Code ID 589                    │
  │                                                          │
  │  CreateAgreement → Active → Delivered → Confirmed        │
  │                         ↘ Disputed → Resolved            │
  │                    (window expires) → ClawedBack          │
  └──────────────────────────────────────────────────────────┘
           │                                      │
           │  Agreement data                      │  confirmDelivery()
           │  (on-chain state)                    │  (proof hash)
           ▼                                      ▼
  ┌──────────────────────────────────────────────────────────┐
  │               TX Blockchain                    │
  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
  │  │ Smart    │ │ CosmWasm │ │ On-chain │ │ Explorer   │ │
  │  │ Tokens   │ │ Runtime  │ │ DEX      │ │ Verify     │ │
  │  └──────────┘ └──────────┘ └──────────┘ └────────────┘ │
  └──────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴──────────┐
                    │  Action Handlers   │
                    │                    │
                    │ PriceOracleHandler │
                    │ ComputeHandler     │
                    │ DataFeedHandler    │
                    │ ImageGenHandler    │
                    │ FunctionHandler    │
                    └────────────────────┘

Get Building in Minutes

Connect & Escrow

Autonomous Agent

Core Modules

TXToken

AgentPayments

EscrowContract

EscrowOracleAgent

Action Handlers

AgentRegistry

OracleJury

FungibleOps

NFTOps / DexOps

Escrow Contract API

Execute Messages

Query Messages

SDK Usage

Agreement Lifecycle

TXAI Memo Protocol

Examples

Parse & Encode

Action Handlers

PriceOracleHandler

ComputeHandler

ImageGenHandler

FunctionHandler (Custom)

ActionHandler Interface

Autonomous Agent Setup

Full Multi-Action Agent

Pipeline Flow

Events

Architecture

Ready to build?