Tutorial

Hello-World Bot

A minimal Python bot, unprotected then ATF-protected, in under 30 lines per script. See exactly what changes when you add a policy gate, receipts, and fail-closed enforcement.

What This Example Is

Two Python scripts that do the same thing: construct a tiny SOL-to-USDC swap intent, apply a trivial "should I trade?" rule, and simulate execution. One script runs raw. The other routes through ATF first.

The bot logic is intentionally identical between the two scripts so the only difference is the ATF wrapper.

Teaching example only

Execution is simulated with deterministic sample data. This is not production trading code. The goal is to compress the learning curve so you can see exactly where ATF plugs in.

What You Learn

How little code changes when you add ATF to an existing bot
What a policy gate does at the execution boundary
Why fail-closed matters when ATF is unreachable or policy denies the intent
What a receipt proves and why it exists
Where operator control lives without touching bot code

Before and After

Unprotected Bot

Build a swap intent (SOL to USDC, 0.001 SOL)
Apply a hard-coded rule: is the amount below a cap?
If yes, execute immediately (simulated)
Done. No audit trail, no operator control, no proof.

Intent -> Local rule -> Execute (no gate)
                         No receipt
                         No operator control

ATF-Protected Bot

Build the same swap intent
Apply the same local rule
Send the intent through ATF (policy gate)
ATF checks policy, returns a typed decision + receipt
If allow=true, execute (simulated)
If allow=false, stop cleanly (fail-closed)
Receipt and proof identifiers available for audit

Intent -> Local rule -> ATF policy gate -> Execute (if OK)
                                            Receipt / proof
                                            Operator control

The key insight: the bot code barely changes. ATF wraps the execution boundary, not the strategy. The protected version adds roughly three lines of ATF integration on top of the same logic.

What ATF Adds

#	Capability	What It Means
1	Policy gate	The intent is checked against operator-defined rules before any execution happens.
2	Deterministic decisioning	ATF returns a typed, machine-readable result (allow/deny + reason codes). No string parsing.
3	Receipt and proof	Every decision produces a tamper-evident receipt reference for audit and verification.
4	Operator control	Operators can change policy, revoke permits, or kill-switch bots without touching bot code.
5	Intelligence feedback loop	Execution outcomes feed back into the system so future decisions can improve over time.

Fail-Closed Behavior

When ATF is unreachable or not configured, the protected bot does not execute. This is intentional. The example demonstrates four outcomes:

Scenario	Decision	Bot Executes?
ATF running, policy permits	allow	Yes
ATF running, policy denies	deny	No (fail-closed)
ATF unreachable or bad config	config_error	No (fail-closed)
Permit expired before execution	permit_expired	No (fail-closed)

In every denial case, the bot prints exactly why it stopped, using machine-readable status codes.

Why the Example Uses Simulated Execution

The bot is intentionally simple. The swap is simulated, not submitted on-chain. This keeps the example focused on the ATF integration boundary rather than Solana transaction mechanics.

If you understand a 30-line bot, you can see exactly where ATF plugs in. If the bot were a full strategy engine, the integration would be buried in noise.

To move to real execution, you would replace the simulated execution function with one that builds a Jupiter swap transaction, signs it, and submits it via RPC. The ATF integration stays the same.

Source Example

The full source lives in the ATF repository at examples/hello-world-bot/. The directory contains four files:

File	Description
unprotected_bot.py	Raw bot: decide locally, execute immediately
protected_bot.py	Same bot, routed through ATF first
env.example	Sample environment variables for ATF connection
README.md	Full walkthrough with expected output

The ATF repository is currently private. View on GitHub ↗ (requires repo access). When the repository becomes public, this link will resolve for all users.

Next Steps

First Protected Trade

Protect a real swap intent, receive a receipt, and verify it end to end

Integration Pattern

How agents call ATF before execution and consume deterministic decisions

MCP Integration

Hosted MCP endpoint with five tools for agent runtimes

Policy Model

Allowlists, limits, slippage bounds, cooldowns, and fail-closed checks