Skip to main content

​
What You’ll Build

A TypeScript agent that:
  1. Takes a natural language task as input
  2. Discovers the right service on ACN
  3. Pays for and executes the call
  4. Returns the result
By the end, you’ll have a working agent that can autonomously use any service on ACN.

​
Prerequisites

​
Step 1: Scaffold the Project

npx acn-agent create my-first-agent
When prompted:
  • Framework: Choose your preferred framework (or “Bare TypeScript” to start simple)
  • API Key: Paste your acn_sk_... key
  • Wallet: Enter a private key or generate a new one
  • Network: Select mainnet (or testnet for testing)
  • Max cost per task: Start with $1.00
cd my-first-agent
npm install

​
Step 2: Understand the Generated Code

The scaffolded project includes: 
my-first-agent/
├── src/index.ts          # Your agent's entry point
├── agent.config.json     # MCP server + LLM configuration
├── .env                  # API keys and wallet (gitignored)
└── package.json
The .env file contains your credentials: 
ACN_API_KEY=acn_sk_your_key
WALLET_PRIVATE_KEY=0x...

​
Step 3: Write Your Agent

Here’s a minimal agent using the REST API (no framework dependencies): 
// src/index.ts

const ACN_BASE = "https://api.acn.exchange";
const API_KEY = process.env.ACN_API_KEY!;

async function discover(query: string) {
  const res = await fetch(`${ACN_BASE}/v1/discover`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query }),
  });
  return res.json();
}

async function execute(providerId: string, endpointSlug: string, payload: any) {
  const res = await fetch(`${ACN_BASE}/v1/execute/${providerId}/${endpointSlug}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`,
    },
    body: JSON.stringify(payload),
  });
  return res.json();
}

async function main() {
  // Step 1: Discover a cryptocurrency price service
  console.log("🔍 Discovering services...");
  const discovery = await discover("get current cryptocurrency prices");

  const best = discovery.results[0];
  console.log(`Found: ${best.provider_name} — ${best.description}`);
  console.log(`Cost: $${best.pricing.price_per_call_usdc} USDC/call`);

  // Step 2: Execute the call
  console.log("\n⚡ Executing...");
  const result = await execute(best.provider_id, best.endpoint_slug, {
    ids: "bitcoin,ethereum",
    vs_currencies: "usd",
  });

  console.log("\n📊 Results:");
  console.log(JSON.stringify(result.data, null, 2));
  console.log(`\n💰 Cost: $${result.acn.charged_usdc} USDC`);
  console.log(`💳 Remaining balance: $${result.acn.remaining_balance_usdc} USDC`);
}

main().catch(console.error);

​
Step 4: Run It

npx tsx src/index.ts
Expected output: 
🔍 Discovering services...
Found: CoinGecko — Get current cryptocurrency prices
Cost: $0.001 USDC/call

⚡ Executing...

📊 Results:
{
  "bitcoin": { "usd": 67542.00 },
  "ethereum": { "usd": 3521.80 }
}

💰 Cost: $0.001 USDC
💳 Remaining balance: $9.999 USDC

​
Step 5: Make It Smarter

Now let’s add an LLM to make decisions. Here’s an example using the Vercel AI SDK: 
import { generateText } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { tool } from "ai";
import { z } from "zod";

const { text } = await generateText({
  model: anthropic("claude-sonnet-4-20250514"),
  tools: {
    acn_discover: tool({
      description: "Search ACN for services",
      parameters: z.object({ query: z.string() }),
      execute: async ({ query }) => discover(query),
    }),
    acn_execute: tool({
      description: "Execute an ACN service",
      parameters: z.object({
        provider_id: z.string(),
        endpoint_slug: z.string(),
        payload: z.record(z.any()),
      }),
      execute: async ({ provider_id, endpoint_slug, payload }) =>
        execute(provider_id, endpoint_slug, payload),
    }),
  },
  maxSteps: 5,
  prompt: "Get the current Bitcoin price and tell me if it's above $60,000",
});

console.log(text);

​
What’s Next?

Equip Agent with Wallet

Set up autonomous payments for your agent

Agent Frameworks

Integrate with LangChain, CrewAI, and more

MCP Server

Use native MCP tools instead of REST

Discovery Deep Dive

Understand how discovery ranking works