Golden Path

Your First Protected Trade

Submit a swap, receive a receipt, verify the hash. No new dependencies required.

See the specification: Receipt format and verification procedure are normatively defined in atf-spec → spec/receipt.md and spec/verification.md.

This page uses API-level terms (allow, approved). For the full mapping across spec, API, CLI, and UI see the terminology & endpoint glossary.

Install the CLI

Recommended: install globally

npm install -g @trucore/atf@1.5.1

Then run commands directly with atf.

Alternative: run without installing

npx @trucore/atf@1.5.1 trade

Run Your First Protected Trade

When you run this: ATF evaluates a trade, shows the decision, and generates a receipt. No real transaction is submitted.

Demo mode

No wallet required
No on-chain execution
Simulated protected trade

Real mode

Requires setup (atf setup)
Executes on Solana mainnet
Enforced by ATF policy

1. Try a protected trade

atf trade

2. Connect for real trades

atf setup

3. Check readiness

atf doctor

4. Verify proof

atf verify <receipt-id>

Who This Is For

Trading bot developers protecting Jupiter, Raydium, or Orca swaps on Solana
AI agent builders adding policy-enforced guardrails before chain execution
Anyone who wants to verify that ATF evaluates, receipts, and enforces before a transaction lands

The Flow

Intent→Policy Check→Decision + Receipt→Verify

If allow=true, proceed to sign and send. If allow=false, abort (fail-closed). Either way, the receipt proves what ATF decided.

Step 1: Define Your Intent

A standard SOL → USDC swap on Jupiter. Every field is plain JSON, no SDK required.

intent.json

{
  "chain_id": "solana",
  "intent_type": "swap",
  "intent": {
    "type": "swap",
    "in_mint": "So11111111111111111111111111111111111111112",
    "out_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount_in": 1000000,
    "slippage_bps": 50,
    "agent_id": "my-bot-v1"
  },
  "metadata": {
    "agent_version": "1.0.0",
    "session_id": "golden-path-001"
  }
}

Step 2: Protect the Intent

Pick your preferred integration path. All produce the same response contract.

Building through MCP?

If your agent runtime supports MCP, the hosted endpoint covers the full advisory-to-enforcement loop with five tools including protect_transaction and verify_receipt. See MCP Integration for setup and the complete tool inventory. If you are not using MCP, continue with the HTTP or CLI paths below.

HTTP (curl)

bash

BASE_URL="${BASE_URL:-https://api.trucore.xyz}"

curl -sS "$BASE_URL/v1/bot/protect" \
  -H "Content-Type: application/json" \
  -d '{
    "chain_id": "solana",
    "intent_type": "swap",
    "intent": {
      "type": "swap",
      "in_mint": "So11111111111111111111111111111111111111112",
      "out_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount_in": 1000000,
      "slippage_bps": 50,
      "agent_id": "my-bot-v1"
    }
  }'

Python (zero dependencies)

python

"""protect_golden.py - zero-dependency protect call."""
import json, urllib.request

BASE_URL = "https://api.trucore.xyz"  # or http://localhost:8000
INTENT = {
    "chain_id": "solana",
    "intent_type": "swap",
    "intent": {
        "type": "swap",
        "in_mint": "So11111111111111111111111111111111111111112",
        "out_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "amount_in": 1000000,
        "slippage_bps": 50,
        "agent_id": "my-bot-v1",
    },
}

req = urllib.request.Request(
    f"{BASE_URL}/v1/bot/protect",
    data=json.dumps(INTENT).encode(),
    headers={"Content-Type": "application/json"},
)
with urllib.request.urlopen(req, timeout=20) as resp:
    result = json.loads(resp.read())

print(json.dumps(result, indent=2))
if result.get("allow"):
    print(f"ALLOWED - receipt hash: {result['receipt']['content_hash']}")
else:
    print(f"DENIED - reason codes: {result.get('reason_codes', [])}")

TypeScript / Node.js (zero dependencies)

javascript

// protect_golden.mjs - zero-dependency protect call (Node 18+)
const BASE_URL = process.env.BASE_URL ?? "https://api.trucore.xyz";
const intent = {
  chain_id: "solana",
  intent_type: "swap",
  intent: {
    type: "swap",
    in_mint: "So11111111111111111111111111111111111111112",
    out_mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    amount_in: 1_000_000,
    slippage_bps: 50,
    agent_id: "my-bot-v1",
  },
};

const res = await fetch(`${BASE_URL}/v1/bot/protect`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(intent),
});
const result = await res.json();
console.log(JSON.stringify(result, null, 2));

if (result.allow) {
  console.log("ALLOWED - receipt hash:", result.receipt.content_hash);
} else {
  console.log("DENIED - reason codes:", result.reason_codes);
}

CLI

bash

cat intent.json | atf bot protect --stdin

Exit codes: 0 = ALLOW, 20 = DENY, 31 = CONFIG_ERROR. Install: npm install -g @trucore/atf, or run directly with npx @trucore/atf

OpenClaw Plugin

If you use OpenClaw, install the ATF plugin and call atf_protect_intent with the same intent shape.

bash

openclaw plugins install @trucore/trucore-atf@0.2.11

Example protected execution

SOL → USDC swap
DEX: Jupiter
Policy enforcement: enabled
Execution receipt generated

Verify a receipt →

Step 3: Read the Response

Allowed

{
  "allow": true,
  "reason_codes": [],
  "warnings": [],
  "receipt": {
    "decision": "approved",
    "reasons": [],
    "content_hash": "a1b2c3d4e5f6...64-char-hex-string",
    "hash_version": "1",
    "timestamp_utc": "2026-03-14T00:00:00+00:00",
    "chain_id": "solana",
    "intent_type": "swap"
  },
  "venue": "jupiter"
}

Denied

{
  "allow": false,
  "reason_codes": ["DEX_SLIPPAGE_TOO_HIGH"],
  "receipt": {
    "decision": "denied",
    "reasons": ["DEX_SLIPPAGE_TOO_HIGH"],
    "content_hash": "f9e8d7c6b5a4...64-char-hex-string",
    "hash_version": "1"
  }
}

Key Fields

Field	Meaning
allow	`true` = proceed. `false` = abort.
reason_codes	Empty on allow. Specific deny codes on deny.
receipt.content_hash	SHA-256 deterministic hash. Same input = same hash.
receipt.decision	`"approved"` or `"denied"`
venue	Detected DEX (jupiter, raydium, orca)

Step 4: Verify the Receipt

The receipt hash proves what ATF decided. Verify it independently using any of these methods:

CLI

bash

atf receipts verify --hash a1b2c3d4e5f6...full_hash_here

HTTP

bash

curl -sS "$BASE_URL/v1/receipts/verify" \
  -H "Content-Type: application/json" \
  -d '{"content_hash": "a1b2c3d4e5f6..."}'

Web

Paste the content_hash into the Receipt Verifier.

What verification proves

Receipt content is intact (hash integrity)
Decision fields are untampered (deterministic hash match)
Decision is reproducible (same input = same hash)

What verification does NOT prove

That the transaction was submitted to chain
That on-chain result matched the intent

See Anchoring Roadmap for planned on-chain receipt anchoring.

Step 5: Success Markers

You have completed the golden path when:

Marker	How to Confirm
✓ Intent submitted	HTTP 200 received (or CLI exit code 0 / 20)
✓ Decision received	`allow` field is true or false
✓ Receipt returned	`content_hash` is a 64-character hex string
✓ Receipt verified	CLI verify returns valid, or web verifier shows check
✓ Deny codes understood	If denied, `reason_codes` lists violations

What This Proves

Your bot now has a policy-enforced firewall. Every intent is:

Evaluated against configurable policy (spend caps, slippage bounds, protocol allowlists)
Decided deterministically (same input → same output, every time)
Receipted with a tamper-evident SHA-256 hash
Verifiable independently by any party with the receipt

Want the smallest possible before-and-after example?

The hello-world bot tutorial shows a minimal Python bot first without ATF, then with ATF protection. Simulated execution, educational, and under 30 lines per script.

Next Steps

Verification Deep Dive

What content_hash means and production verification patterns

Integration Pattern

How agents call ATF before execution

MCP Integration

Hosted MCP endpoint with five tools for agent runtimes

Policy Model

Allowlists, limits, slippage bounds, cooldowns

CLI Reference

Full CLI for profiles, transactions, receipts, and more

API Reference

Public endpoints for simulation and receipt generation

OpenClaw Plugin

Agent-native policy protection with 13 tools

Receipt Specification

Formal receipt contract, hash rules, version policy

Receipt Verifier

Paste a content_hash and verify it now

Example Verified Receipt

A stable, canonical receipt you can inspect and share

Wrong package name?

If you see npm ERR! 404 for @trucore/atf-cli, use the correct package name:

npm install -g @trucore/atf

The published package is @trucore/atf. The binary is atf.

You protected a trade. Now verify it.

Paste the content_hash from your receipt into the verification tool to confirm integrity and complete the golden path.

Verify your receipt →Open your portal

Don't have access yet? Apply for early access or see all builder paths.