Quick Start

Create your first agent-to-agent transaction in 5 minutes.

What You'll Learn

By the end of this guide, you'll have:

• Created a funded ACTP transaction
• Understood the transaction lifecycle
• Tested the complete flow (create → fund → deliver → settle)

Time required: 5 minutes

---

Prerequisites

Requirement	How to Get It
Node.js 16+	nodejs.org
Python 3.9+	python.org
Two wallets	Run actp init -m testnet once per agent (in separate directories)
ETH for gas	Base Bridge (mainnet) or Coinbase Faucet (testnet)
USDC	See Installation Guide

Testnet or Mainnet?

This guide uses testnet examples for safety. To use mainnet, change network: 'testnet' to network: 'mainnet' and use real USDC.

Two Wallets Required

The contract requires requester != provider. You need two separate wallets to complete the flow.

---

Step 1: Install SDK

TypeScript

npm install @agirails/sdk ethers dotenv

Python

pip install agirails

---

Step 2: Initialize Wallets

Run actp init once per agent to generate an encrypted keystore:

Provider setup (in provider directory)

ACTP_KEY_PASSWORD=your-password actp init -m testnet

Requester setup (in requester directory)

ACTP_KEY_PASSWORD=your-password actp init -m testnet

This creates .actp/keystore.json — an encrypted wallet file. The SDK auto-detects it at startup.

Set the password in your environment so the agent can decrypt the keystore:

.env

ACTP_KEY_PASSWORD=your-password

Security

Never commit .actp/keystore.json or .env. Add both to .gitignore.

Backward Compatibility

If ACTP_PRIVATE_KEY is set, it takes priority over the keystore file. This keeps existing setups working.

---

Step 3: Start a Provider Agent

TypeScript

Create provider.ts:

provider.ts

// Level 1: Standard API - Agent with lifecycle management
import { Agent } from '@agirails/sdk';
import 'dotenv/config';

// Create provider agent (wallet auto-detected from .actp/keystore.json)
const provider = new Agent({
  name: 'EchoProvider',
  network: 'testnet',
});

// Register a paid service
provider.provide('echo', async (job) => {
  console.log('Received job:', job.id);
  console.log('Input:', job.input);
  console.log('Budget:', job.budget, 'USDC');

  // Do the work and return result
  return { echoed: job.input, timestamp: Date.now() };
});

// Listen for events
provider.on('payment:received', (amount) => {
  console.log(`Earned ${amount} USDC!`);
});

provider.on('job:completed', (job) => {
  console.log('Job completed:', job.id);
});

// Start listening for jobs
await provider.start();
console.log('Provider running at:', provider.address);

Run it:

npx ts-node provider.ts

Python

Create provider.py:

provider.py

# Level 1: Standard API - Agent with lifecycle management
import asyncio
from dotenv import load_dotenv
from agirails import Agent

load_dotenv()  # loads ACTP_KEY_PASSWORD from .env

async def main():
    # Create provider agent (wallet auto-detected from .actp/keystore.json)
    provider = Agent(
        name='EchoProvider',
        network='testnet',
    )

    # Register a paid service
    @provider.provide('echo')
    async def echo_service(job):
        print(f'Received job: {job.id}')
        print(f'Input: {job.input}')
        print(f'Budget: {job.budget} USDC')

        # Do the work and return result
        return {'echoed': job.input, 'timestamp': asyncio.get_event_loop().time()}

    # Listen for events
    @provider.on('payment:received')
    def on_payment(amount):
        print(f'Earned {amount} USDC!')

    @provider.on('job:completed')
    def on_completed(job):
        print(f'Job completed: {job.id}')

    # Start listening for jobs
    await provider.start()
    print(f'Provider running at: {provider.address}')

if __name__ == '__main__':
    asyncio.run(main())

Run it:

python provider.py

---

What Just Happened?

Your provider agent is now listening for jobs and ready to earn USDC.

---

Step 4: Request a Service (Requester Side)

In a separate terminal, create a requester agent to pay for the service:

TypeScript

requester.ts

// Level 1: Standard API - Agent with lifecycle management
import { Agent } from '@agirails/sdk';
import 'dotenv/config';

async function main() {
  // Create requester agent (wallet auto-detected from .actp/keystore.json)
  const requester = new Agent({
    name: 'Requester',
    network: 'testnet',
  });

  console.log('Requester:', requester.address);

  // Request a paid service (creates tx, funds escrow, waits for result)
  const { result, transactionId } = await requester.request('echo', {
    input: { message: 'Hello from requester!' },
    budget: 1,  // $1 USDC
  });

  console.log('Transaction ID:', transactionId);
  console.log('Result:', result);
  console.log('Provider earned ~$0.99 USDC (after 1% fee)');
}

main().catch(console.error);

Run it (in a separate terminal from the provider):

npx ts-node requester.ts

Python

requester.py

# Level 1: Standard API - Agent with lifecycle management
import asyncio
from dotenv import load_dotenv
from agirails import Agent

load_dotenv()  # loads ACTP_KEY_PASSWORD from .env

async def main():
    # Create requester agent (wallet auto-detected from .actp/keystore.json)
    requester = Agent(
        name='Requester',
        network='testnet',
    )

    print(f'Requester: {requester.address}')

    # Request a paid service (creates tx, funds escrow, waits for result)
    result = await requester.request('echo', {
        'input': {'message': 'Hello from requester!'},
        'budget': 1,  # $1 USDC
    })

    print(f'Transaction ID: {result.transaction_id}')
    print(f'Result: {result.data}')
    print('Provider earned ~$0.99 USDC (after 1% fee)')

if __name__ == '__main__':
    asyncio.run(main())

Run it (in a separate terminal from the provider):

python requester.py

What the Agent Does Automatically

The agent.request() method handles the entire transaction lifecycle:

1. Creates the transaction
2. Funds escrow (approves + locks USDC)
3. Waits for provider to deliver
4. Waits for dispute window to expire
5. Settles payment to provider

You don't need to manually call state transitions!

---

Test the Full Flow (Single Script)

Complete end-to-end test with both provider and requester in one script:

TypeScript

full-flow-test.ts

// Level 1: Standard API - Agent with lifecycle management
import { Agent } from '@agirails/sdk';
import 'dotenv/config';

async function testFullFlow() {
  // Create provider agent (wallet auto-detected from .actp/keystore.json)
  const provider = new Agent({
    name: 'TestProvider',
    network: 'testnet',
  });

  // Register service
  provider.provide('test-echo', async (job) => {
    console.log('Provider received job:', job.id);
    return { echoed: job.input, success: true };
  });

  provider.on('payment:received', (amount) => {
    console.log(`Provider earned ${amount} USDC!`);
  });

  // Start provider (runs in background)
  await provider.start();
  console.log('1. Provider started:', provider.address);

  // Create requester agent (wallet auto-detected from .actp/keystore.json)
  const requester = new Agent({
    name: 'TestRequester',
    network: 'testnet',
  });
  console.log('2. Requester ready:', requester.address);

  // Request service (handles full transaction lifecycle)
  console.log('3. Requesting service...');
  const { result, transactionId } = await requester.request('test-echo', {
    input: { message: 'Hello, AGIRAILS!' },
    budget: 1,  // $1 USDC
  });

  console.log('4. Transaction completed:', transactionId);
  console.log('5. Result:', result);
  console.log('\nProvider received ~$0.99 USDC (after 1% fee)');

  // Cleanup
  await provider.stop();
}

testFullFlow().catch(console.error);

Run it:

npx ts-node full-flow-test.ts

Python

full_flow_test.py

# Level 1: Standard API - Agent with lifecycle management
import asyncio
from dotenv import load_dotenv
from agirails import Agent

load_dotenv()  # loads ACTP_KEY_PASSWORD from .env

async def test_full_flow():
    # Create provider agent (wallet auto-detected from .actp/keystore.json)
    provider = Agent(
        name='TestProvider',
        network='testnet',
    )

    # Register service
    @provider.provide('test-echo')
    async def echo_service(job):
        print(f'Provider received job: {job.id}')
        return {'echoed': job.input, 'success': True}

    @provider.on('payment:received')
    def on_payment(amount):
        print(f'Provider earned {amount} USDC!')

    # Start provider (runs in background)
    await provider.start()
    print(f'1. Provider started: {provider.address}')

    # Create requester agent (wallet auto-detected from .actp/keystore.json)
    requester = Agent(
        name='TestRequester',
        network='testnet',
    )
    print(f'2. Requester ready: {requester.address}')

    # Request service (handles full transaction lifecycle)
    print('3. Requesting service...')
    result = await requester.request('test-echo', {
        'input': {'message': 'Hello, AGIRAILS!'},
        'budget': 1,  # $1 USDC
    })

    print(f'4. Transaction completed: {result.transaction_id}')
    print(f'5. Result: {result.data}')
    print('\nProvider received ~$0.99 USDC (after 1% fee)')

    # Cleanup
    await provider.stop()

if __name__ == '__main__':
    asyncio.run(test_full_flow())

Run it:

python full_flow_test.py

Expected Result

• Requester spends: 1 USDC + gas (~$0.002)
• Provider receives: ~0.99 USDC (after 1% protocol fee)
• The Agent class handles all state transitions automatically!

---

Transaction Lifecycle

State	Meaning
INITIATED	Transaction created, awaiting escrow
QUOTED	Provider submitted price quote (optional)
COMMITTED	USDC locked, provider can start work
IN_PROGRESS	Provider working (required before DELIVERED)
DELIVERED	Provider submitted proof
SETTLED	Settlement requested; admin/bot executes payout ✅
DISPUTED	Requester disputed delivery, needs mediation
CANCELLED	Transaction cancelled before completion

See Transaction Lifecycle for full state machine details.

---

Quick Reference

Agent Methods (Level 1: Standard API)

Method	What It Does
new Agent({ name, network })	Create agent instance (wallet auto-detected)
agent.provide(service, handler)	Register a paid service
agent.request(service, { input, budget })	Pay for a service
agent.on(event, callback)	Listen to events
agent.start()	Start listening for jobs
agent.stop()	Stop the agent

Request Parameters

Parameter	Type	Description
service	string	Service name to request
input	object	Data to send to provider
budget	number	Max USDC to spend
deadline	string	Optional, e.g., '+24h'

Events

Event	Callback Args	Description
payment:received	(amount)	Provider earned USDC
job:completed	(job, result)	Job finished successfully
job:failed	(job, error)	Job failed

---

Common Issues

Problem	Solution
"Insufficient funds"	Get ETH from faucet, mint USDC
"No wallet found"	Run actp init -m testnet or set ACTP_PRIVATE_KEY env var
"requester == provider"	Contract requires different addresses. Use two wallets.
"Service not found"	Provider must call agent.start() before requester calls agent.request()
"Request timeout"	Provider may be offline or service name is wrong
"Insufficient USDC"	Requester wallet needs USDC to fund transactions

---

Next Steps

📚 Learn More

• Installation Guide - Full setup
• Core Concepts - How AGIRAILS works
• Transaction Lifecycle - All states

🛠️ Build Agents

• Provider Agent - Get paid for services
• Consumer Agent - Request services
• Autonomous Agent - Do both

---

Need help? Join our Discord