TilcAI documentation

TilcAI is commerce infrastructure between agents: the assistant of a person or organization inquires, quotes and buys from a business with limited authority, verifiable terms and payments on Stellar.

It receives a purchase or booking intent, gets from the business an offer with a verifiable price, availability and payout destination, applies identity, limits and approval, coordinates a payment over a supported rail and links the financial result to the order and to the commercial confirmation. It is being built in stages and names may change. The complete purchase flow is not enabled.

• Available foundation A technical USDC payment from Avalanche Fuji to Stellar Testnet with CCTP, also gasless for the buyer; an x402 rail with an OpenZeppelin Relayer tested in isolation; a deterministic policy evaluator and versioned shared contracts.
• Being integrated MCP connector, quotes and orders, approval per purchase, linking order, payment and delivery, the WhatsApp channel and account issuance.
• Next steps Smart accounts with limited permissions, shared budget across agents, scheduled tasks and more CCTP routes.

A component being available is not the same as a purchase flow being enabled. Nothing here has been audited, and nothing runs with real funds. Every capability, with its evidence and who maintains it, is on the build status page.

What TilcAI builds and what is external

The first flow targets one business, one service, one assistant, one user and one asset on stellar:testnet.

A single operation joins the buyer and the business. Every step has an owner, a state and its own evidence: payment is never confused with delivery.

1. Intent

   The buyer asks for a product or service, the quantity and the conditions. TilcAI structures the intent and records the authenticated principal.

   State

   Requested

   Evidence

   Message and authenticated principal

2. Offer

   The business consults its source of truth and returns an identified quote, with validity, asset, amount, costs, availability and the registered payout destination (payTo). If it cannot guarantee stock or capacity, it confirms before promising it.

   State

   Quoted, or pending confirmation

   Evidence

   quoteId, version, source and time of the availability

3. Verification

   TilcAI verifies the business identity, the payout destination, the offer version, the limits and the policy. A rejection or a pending approval does not start the payment. ALLOW is eligibility: it neither signs nor pays.

   State

   Evaluated

   Evidence

   Decision and reason code

4. Approval

   The person reviews the exact terms on a trusted surface and approves them. The approval commits amount, asset, network, recipient, quoteId, expiry and orderId. A written "yes" in a chat does not replace the authorization.

   State

   Approved

   Evidence

   Approval bound to the order

5. Payment

   The router picks a single route: a direct payment on Stellar with x402, or USDC from another network with CCTP. Every attempt carries an idempotency key.

   State

   Prepared, sent

   Evidence

   paymentAttemptId and chosen route

6. Reconciliation

   TilcAI checks the on-chain evidence and links orderId, quoteId, paymentAttemptId, source hash, attestation and destination hash. A timeout is UNCERTAIN until reconciled: it is not permission to repeat the payment.

   State

   Settled

   Evidence

   Financial receipt with testnet links

7. Fulfillment

   The business confirms the booking, pickup or delivery separately. Buyer and business see the same order state, each with its own receipt.

   State

   Closed or in follow-up

   Evidence

   The business's confirmation, distinct from the payment receipt

Minimum shared contract

Channels, API and rails share the same identifiers:

• principalId
• agentId
• businessId
• serviceId
• quoteId
• orderId
• paymentAttemptId

On top of them come the commerce, payment and budget states of tilcai-shared-v1, an Idempotency-Key on every write, amounts in atomic units, an unambiguous network and a versioned payTo. The shared contracts are a proposal: the team must review them before fixing them as the final API.

Paid does not mean delivered. If delivery fails after payment, the result is a visible commercial exception, not an automatic conversion. Cancellation and refunds need their own rules and do not exist yet.

A request moves through three planes that stay separate, so it can move forward in the first one without holding permissions in the third. The language model helps with the task; the infrastructure decides which actions can run and under which conditions.

Orders, mandates and states are kept in durable storage: a chat history is not a purchase record. Modules are logical responsibilities, not one service per box.

The business keeps authority over its services, prices, availability, payout destination and delivery confirmation. TilcAI does not invent stock, discounts or confirmations.

Four integration paths

These are onboarding proposals, not a launched product. There is no commerce portal, no real connected catalog and no operational seller agent yet; they are tested first with a bounded pilot business, on testnet. No AI agent or website is needed to start.

What the business keeps

• Explicit capabilities. Each business exposes only the operations it supports, for example checking availability, holding a resource or confirming an order. Permissions distinguish them.
• Context from authentication. Business, user and role come from the authenticated session, never from a free argument proposed by the model.
• Identity with a limited scope. A business registers its operator, origin, keys and payment destination. Controlling a key or a domain does not prove legal identity or commercial quality.
• Signed quotes. A quote binds business, service, quantity, total price, network, asset, recipient, expiry and a hash of the terms.

A buyer accepts a quote only when:

1. the signing key is recognized by an independent source (onboarding, an accepted registry or the principal's trusted configuration), never taken from the quote itself;
2. service, network, asset, amount and recipient match the payment requirements exactly, and the quote has not expired;
3. policy, budget and approval still allow the operation.

A signature protects the terms after signing. It does not protect against a compromised key, a phishing origin or a misconfigured policy, and it never grants spending authority.

Who answers for the business

The seller agent is the operational interface that serves requests through authorized capabilities. It can be a rules service with a human operator as backup (the recommended mode for the pilot, because it is the most verifiable), an assistant managed by TilcAI or the company's own agent connected by API. In every case the model does not set price, stock, payout or authority on its own.

Delivery comes from the business. The order is confirmed and fulfilled by the business's own system, and that evidence is kept apart from the payment receipt. Publishing a business profile requires its approval; adding a profile or exploring a use case does not enable sales. A business is presented as enabled only after its operational flow has been verified.

There are three ways into the same infrastructure. All of them end in the same identity, offer, policy, authorization, order, payment and receipt services: a channel is not the financial authority.

MCP tools

MCP (Model Context Protocol) is the tool interface for compatible assistants. TilcAI is designed to publish an MCP server with specific operations, authenticated following the MCP authorization specification. No MCP server is exposed yet. The names below are the contract designed in tilcai-core, not a published package.

The model works with quote, intent and order IDs. There is no unrestricted tool to send money to an arbitrary address. Price, recipient, quantity, network and asset travel as versioned data; the conversation explains that data but does not redefine it.

• Connecting is not spending. Connection, data access and purchase authority are separate. Selecting an assistant or allowing a tool never grants permission to spend.
• A skill is guidance, not permission. It explains how to inquire, clarify, prepare and report states. The server enforces the rules even if an agent ignores the skill.
• Support is per capability. The client catalog distinguishes reading, quoting, preparing and executing. Supporting MCP does not imply autonomous payments. Every client is tested with its own version and authentication.
• Status today. Every client in the catalog is in preparation. A guide is published for a client only after it has been tested, and no guide asks for a seed phrase, private key or token.

A payment becomes eligible only when four conditions hold at once. A valid signature is not enough to authorize it, and reputation can inform a decision but never bypasses a limit.

1. a recognized identity and an authentic, current offer;
2. an intent bound to an order and an applicable mandate;
3. available and held budget;
4. exact approval or a verifiable delegation.

Decisions and states are different things

The policy engine returns ALLOW, DENY or REQUIRE_APPROVAL. The current prototype returns ALLOW or DENY; human approval is part of the authorization flow. An order keeps separate commerce, payment and budget states, so a paid order can still be waiting for delivery.

Two ways to authorize

• Approval per purchase (first route). The user connects a compatible account and reviews service, amount, asset, network, recipient and terms. The wallet signs an authorization compatible with the rail, which on Stellar x402 means a Soroban authorization entry. A login signature or a wallet connection is not enough. If the offer or the invocation changes, a new approval is required.
• Limited delegation (target route). A Soroban smart account owned by the user accepts a restricted signer within a mandate: exact network and asset, allowed contracts, recipients, per-operation and per-period amounts, providers, expiry and revocation. It is enabled only after the account, signer and rail are tested together.

When something goes wrong

• Uncertain payment. A timeout after sending is not a failure. The budget hold is kept and the same attempt is reconciled before anything is signed again. Retrying a query can be safe; retrying a financial execution requires knowing the state of the previous attempt.
• Payment without delivery. The order is not marked delivered. The issue is resolved under the commercial terms, and repeating the purchase is not an automatic fix.
• Revocation. Revoking a mandate blocks new signatures. It does not reverse a payment that already settled.
• Changed terms. A different price, provider or service stops the operation for a new approval. The agent cannot raise its own limit or approve its own exception.

TilcAI picks a single route for each order. A direct payment on Stellar and a cross-network payment with CCTP are alternatives, not two charges for the same order, and they do not yet form an integrated commercial checkout.

Lifecycle of a cross-network payment

A payment moves through stored states: a retry resumes from the last one and never repeats the burn.

1. AWAITING_BURNPayment created, waiting for the signed burn
2. BURN_SUBMITTEDBurn sent; its hash is stored
3. BURN_CONFIRMEDThe receipt and the event match the quote
4. ATTESTEDCircle attested and the message was verified again
5. MINT_SUBMITTEDThe Relayer sent the mint
6. SETTLEDMint confirmed; USDC at the destination and a payment receipt

• A burn backs a single payment and a CCTP nonce a single settlement.
• The mint is idempotent. It is retried without risk, and a second burn is never created for an existing payment.
• The signature commits the exact terms. In gasless mode the Relayer can only send what the payer signed.
• Uncertainty is reconciled. A burn that is not found or an attestation that does not match goes to UNCERTAIN and is not minted; it is never marked failed without evidence.

Network coverage

The tilcai-cctp-engine lab models eight test networks. TilcAI's backend vouches for a single complete corridor.

• Avalanche FujiVerified in TilcAI
• Ethereum SepoliaVerified in TilcAI
• Arbitrum SepoliaVerified in TilcAI
• Base SepoliaVerified in TilcAI
• Arc TestnetLab
• Solana DevnetLab
• Sui TestnetLab
• Stellar TestnetDestination · the business's USDC

"Lab" means code, a route matrix and contract verification; each route still lacks its end-to-end transfer and reconciliation. Circle supporting a network does not enable it in TilcAI: networks are enabled one by one, when each passes its test. CCTP moves native USDC: it does not convert bolivianos or other tokens, and someone who already holds USDC on Stellar does not need it.

The technical detail, payloads and error contract of the x402 rail are in the payment rail documentation of the open tilcai-core repository.

The account belongs to the person or the organization; it is not a "bot's wallet". The agent is software authorized to request actions; it does not own the funds.

Account issuance is in preparation: there is a plan, base contracts and defined ports. The API that issues accounts, tested recovery and deployments are still pending.

Creating an account from a chat

The chat only starts the process and shows states. A secure web screen, tied to a short session, is the boundary for identity, credentials and signatures.

1. The channel generates a single-use link with an expiry. No seeds or keys are sent through the chat.
2. The browser opens an HTTPS origin of TilcAI and the person creates their owner credential, preferably a passkey; otherwise a key of their own or the connection of an existing wallet.
3. TilcAI associates the public key with the authenticated principal and requests the account with an idempotency key. Technical credentials stay on the server.
4. The account provider computes the address and deploys the smart account; it marks it active only after checking the deployment on-chain. The Relayer pays the fee and does not become the owner.
5. The person sees their address, the network, the asset and how to fund. Creating an account does not fund it.
6. To buy, an exact owner approval is prepared. Later delegation is optional, limited and revocable.

How it is funded

TilcAI does not credit a balance from a captured QR or an unauthenticated notice: a deposit is credited only on verifiable confirmation from the provider.

Recovery

Losing the phone, changing the WhatsApp number and recovering an account are different problems. A chat number identifies a conversation; it does not prove ownership of funds by itself, and nobody should be able to reassign an account because they control that number. The recovery design must be reviewed before real funds are used.

What happens in the backend is recorded as events with an order that only grows, reaches the site signed and is interpreted in Spanish and English. Watching cannot break what is watched.

• The backend is the source of truth. It records each event with a position that only grows; the site keeps a recent copy and nothing more.
• The backend pushes. It can live behind a private network, so it is the one that starts the connection, with a signed delivery.
• At least once and in order. If the site was down, it receives what it missed afterwards; repeats are discarded by identifier.
• Monitoring does not break what is monitored. Emitting an event never fails and never waits on the network.

Notices are for seeing, not for deciding: a payment or a disbursement is only considered settled when TilcAI checked the chain itself.

Channel security

• One secret per direction. One protects writes (backend to site) and another reads (person to site). Neither reaches the browser.
• A delivery expires. The signature covers the time, and the site rejects anything older than five minutes.
• No secrets in events. They do carry public addresses, balances, amounts and hashes, which is why reading requires a credential.
• The browser never talks to the backend nor knows its address.

The full path is implemented and verified locally against testnet services. The /en/monitor view is a working base without its final design. Still missing are the dashboard, a durable store on the site (today it is memory and does not work with several instances) and pointing the real relayer at TilcAI.

• The model proposes; rules decide. Model output is never trusted for price, recipient or approval. An unverifiable condition blocks the operation or asks for human review.
• The signer is a separate boundary. Keys stay away from the model and from business data. This website stores no private keys, financial tokens or spending mandates.
• Facilitator and Relayer dependency. Settlement relies on an x402 facilitator and an OpenZeppelin Relayer. If they are unavailable, payments stop.
• Testnet only. The backend rejects any environment other than testnet, and testnet and mainnet will be configured and enabled separately. There are no real funds.
• A lab is not a product. Eight modeled networks are not eight commercial corridors: today four are verified.
• Not audited. Nothing described here has been audited.

Out of scope for now: an agent marketplace, trading or DeFi, wrapped-asset bridges between chains (paying across networks with CCTP, which retires and issues native USDC, is planned and today Avalanche Fuji, Ethereum Sepolia, Arbitrum Sepolia and Base Sepolia to Stellar are verified), free-form price negotiation, purchases from any business without an adapter, regulated services, converting bolivianos without a verified provider and unlimited agent autonomy.

These are planned, not active. They are added behind the same operations and states.

• Planned extension A2A. A standard for agent-to-agent communication, with capabilities described by Agent Cards. It would connect a buyer's request to a business agent's capabilities. It does not replace inventory, a mandate or a financial signature. The first flow can run on MCP and a commercial API.
• Planned extension ERC-8004. A draft standard for identity, reputation and validation registries on Ethereum/EVM. It is not a native Stellar contract and does not guarantee trust. TilcAI plans a native operational identity on Stellar and, separately, an adapter to resolve an EVM registry. Reading an EVM identity never moves funds between networks or builds a bridge.
• Next steps Smart accounts, shared budget and scheduled tasks. See the build status.

Principal

The person or organization that owns the funds and grants authority.

Mandate

Authority delegated to an agent, with scope, limits, period and revocation.

Quote

Exact commercial terms from a business: service, price, asset, network, recipient and expiry.

Intent

The purchase a person wants to make, bound to a quote and immutable once created.

Order

The commercial operation linking principal, business and quote, with its own states.

MCP

Model Context Protocol: the tool interface for compatible assistants.

A2A

A standard for agent-to-agent communication. It is a planned extension, not a requirement of the first flow.

x402

An HTTP payment protocol: a server answers 402 Payment Required with payment terms and the client pays to obtain the resource.

Facilitator

The component that verifies and submits an x402 payment. Here, a plugin running in an OpenZeppelin Relayer.

OpenZeppelin Relayer

A service that sends transactions with the networks, signers and policies configured on it. It can pay the network fee without becoming the owner of the funds.

CCTP

Circle's protocol that moves native USDC between networks: it burns it at the source, waits for an attestation and mints it at the destination.

Attestation

Circle's signature (the Iris service) proving the burn happened and allowing the mint at the destination.

Soroban

Stellar's smart contract platform.

Smart account

A programmable account whose rules, signers and limits are defined by a contract.

Idempotency

Repeating an operation with the same key yields the same result and does not run it twice.

Tenant

The isolated space of a business or integrator, with its identity, quotas and roles.

Vault

A TilcAI contract on Avalanche Fuji that executes disbursements subject to a budget, a per-payment limit and a pause.

Reconciliation

Establishing the real result of a payment attempt, including when a call failed midway.

Reason code

A machine-readable explanation of a decision.

This page summarizes the team's official context, cut at 8 and 9 October 2026, and the code of the repositories. The code and its tests determine what is implemented; a testnet run proves the route that was reproduced, not every planned route.

• From the open tilcai-core repository: shared contracts, MCP tools, intent and mandate, payment rail on testnet and rail reproducibility.
• External references: OpenZeppelin Relayer, smart accounts on Stellar, CCTP networks and domains and MCP tools.