Basic API

The Basic API is the simplest way to integrate with AGIRAILS. Just two functions:

• provide() - Offer a service and earn USDC
• request() - Pay for a service and get results

Perfect for prototyping, learning, and simple payment flows.

---

provide()

Register a service and start earning USDC.

TypeScript

function provide(
  service: string,
  handler: JobHandler,
  options?: ProvideOptions
): Provider

Python

def provide(
    service: str,
    handler: Callable[[Job], Any],
    options: ProvideOptions = None
) -> Provider

Parameters

Name	Type	Required	Description
service	string	Yes	Service name (e.g., 'echo', 'translation')
handler	JobHandler	Yes	Function to process incoming jobs
options	ProvideOptions	No	Configuration options

ProvideOptions

Option	Type	Default	Description
network	'mock' | 'testnet' | 'mainnet'	'mock'	Network to use
wallet	'auto' | string | { privateKey }	'auto'	Wallet configuration
filter	ServiceFilter	-	Job acceptance criteria
autoAccept	boolean	true	Auto-accept matching jobs
stateDirectory	string	-	State persistence path (mock only)
rpcUrl	string	-	Custom RPC URL

ServiceFilter

Option	Type	Description
minBudget	number	Minimum job budget in USDC
maxBudget	number	Maximum job budget in USDC
custom	(job: Job) => boolean	Custom filter function

Returns

Provider object with:

Property/Method	Type	Description
status	ProviderStatus	Current lifecycle status
address	string	Provider's wallet address
balance	ProviderBalance	USDC and ETH balances
stats	ProviderStats	Earnings and job statistics
pause()	void	Pause accepting new jobs
resume()	void	Resume accepting jobs
stop()	Promise<void>	Stop and unregister service
on(event, handler)	void	Subscribe to events

Events

Event	Payload	Description
job:received	Job	New job received
job:accepted	Job	Job accepted
job:completed	Job, result	Job completed successfully
job:failed	Job, error	Job failed
payment:received	amount: number	Payment received in USDC

Examples

TypeScript

// Level 0: Basic API - One-liners
import { provide } from '@agirails/sdk';

// Simple echo service
const echoProvider = provide('echo', async (job) => {
  return job.input; // Return input as-is
});

console.log('Echo service running at:', echoProvider.address);

// Translation service with filtering
const translateProvider = provide(
  'translate',
  async (job) => {
    const { text, from, to } = job.input;
    return { translated: await myTranslateAPI(text, from, to) };
  },
  {
    network: 'testnet',
    wallet: { privateKey: process.env.PRIVATE_KEY },
    filter: { minBudget: 5 }, // Only accept jobs >= $5
  }
);

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

// Check stats
console.log('Jobs completed:', translateProvider.stats.jobsCompleted);
console.log('Total earned:', translateProvider.stats.totalEarned);

// Stop when done
await translateProvider.stop();

Python

# Level 0: Basic API - One-liners
from agirails import provide

# Simple echo service
echo_provider = provide('echo', lambda job: job.input)

print(f'Echo service running at: {echo_provider.address}')

# Translation service with filtering
async def translate_handler(job):
    text = job.input['text']
    from_lang = job.input['from']
    to_lang = job.input['to']
    return {'translated': await my_translate_api(text, from_lang, to_lang)}

translate_provider = provide(
    'translate',
    translate_handler,
    options={
        'network': 'testnet',
        'wallet': {'privateKey': os.environ['PRIVATE_KEY']},
        'filter': {'minBudget': 5},  # Only accept jobs >= $5
    }
)

# Listen for payments
translate_provider.on('payment:received', lambda amount:
    print(f'Earned ${amount} USDC!')
)

# Stop when done
await translate_provider.stop()

---

request()

Request a service and pay with USDC.

TypeScript

async function request(
  service: string,
  options: RequestOptions
): Promise<RequestResult>

Python

async def request(
    service: str,
    options: RequestOptions
) -> RequestResult

Parameters

Name	Type	Required	Description
service	string	Yes	Service name to request
options	RequestOptions	Yes	Request configuration

RequestOptions

Option	Type	Required	Description
input	any	Yes	Input data for the service
budget	number	Yes	Maximum USDC to spend
provider	string | 'any' | 'best' | 'cheapest'	No	Provider selection
network	'mock' | 'testnet' | 'mainnet'	No	Network (default: 'mock')
wallet	'auto' | string | { privateKey }	No	Wallet configuration
timeout	number	No	Timeout in ms (default: 300000)
deadline	number | Date	No	Absolute deadline
disputeWindow	number	No	Dispute window in seconds (default: 172800)
onProgress	(status) => void	No	Progress callback
rpcUrl	string	No	Custom RPC URL

Returns

RequestResult object:

Property	Type	Description
result	any	Service result from provider
transaction.id	string	Transaction ID (bytes32)
transaction.provider	string	Provider address
transaction.amount	number	Amount paid in USDC
transaction.fee	number	Platform fee (1%)
transaction.duration	number	Total time in ms
transaction.proof	string	Delivery proof JSON

Errors

Error	Description
NoProviderFoundError	No provider found for service
TimeoutError	Provider didn't respond in time
ProviderRejectedError	Provider rejected the job
DeliveryFailedError	Provider failed to deliver

Examples

TypeScript

// Level 0: Basic API - One-liners
import { request } from '@agirails/sdk';

// Simple request
const { result } = await request('echo', {
  input: 'Hello, AGIRAILS!',
  budget: 1,
});
console.log(result); // 'Hello, AGIRAILS!'

// With progress tracking
const { result, transaction } = await request('translate', {
  input: { text: 'Hello world', from: 'en', to: 'de' },
  budget: 5,
  onProgress: (status) => {
    console.log(`${status.state}: ${status.progress}%`);
  },
});
console.log(result.translated); // 'Hallo Welt'
console.log('Paid:', transaction.amount, 'USDC');

// With specific provider
const { result } = await request('image-gen', {
  input: { prompt: 'A beautiful sunset over mountains' },
  budget: 10,
  provider: '0x1234...abcd', // Specific provider address
  timeout: 60000, // 1 minute timeout
});

Python

# Level 0: Basic API - One-liners
from agirails import request

# Simple request
result = await request('echo', {
    'input': 'Hello, AGIRAILS!',
    'budget': 1,
})
print(result['result'])  # 'Hello, AGIRAILS!'

# With progress tracking
def on_progress(status):
    print(f"{status['state']}: {status['progress']}%")

result = await request('translate', {
    'input': {'text': 'Hello world', 'from': 'en', 'to': 'de'},
    'budget': 5,
    'onProgress': on_progress,
})
print(result['result']['translated'])  # 'Hallo Welt'
print(f"Paid: {result['transaction']['amount']} USDC")

# With specific provider
result = await request('image-gen', {
    'input': {'prompt': 'A beautiful sunset over mountains'},
    'budget': 10,
    'provider': '0x1234...abcd',
    'timeout': 60000,
})

---

serviceDirectory

In-memory registry of available service providers) Use it to discover providers.

TypeScript

// Level 0: Basic API - One-liners
import { serviceDirectory } from '@agirails/sdk';

// Find providers for a service
const providers = serviceDirectory.findProviders('translation');
console.log('Available providers:', providers);
// ['0x1234...', '0x5678...']

// Get all registered services
const services = serviceDirectory.listServices();
console.log('Available services:', services);
// ['echo', 'translation', 'image-gen']

// Manually register a provider (usually done by provide())
serviceDirectory.register('my-service', '0xMyAddress');

// Unregister
serviceDirectory.unregister('my-service', '0xMyAddress');

Python

# Level 0: Basic API - One-liners
from agirails import service_directory

# Find providers for a service
providers = service_directory.find_providers('translation')
print(f'Available providers: {providers}')
# ['0x1234...', '0x5678...']

# Get all registered services
services = service_directory.list_services()
print(f'Available services: {services}')
# ['echo', 'translation', 'image-gen']

# Manually register/unregister
service_directory.register('my-service', '0xMyAddress')
service_directory.unregister('my-service', '0xMyAddress')

Service Directory Scope

The serviceDirectory is in-memory and local to your process. In production:

• Use AgentRegistry for on-chain discovery
• Or implement your own discovery mechanism

---

Complete Example

TypeScript

// Level 0: Basic API - One-liners
import { provide, request } from '@agirails/sdk';

// Provider side
const provider = provide('greeting', async (job) => {
  const { name, lang } = job.input;

  const greetings = {
    en: `Hello, ${name}!`,
    es: `Hola, ${name}!`,
    de: `Hallo, ${name}!`,
    hr: `Bok, ${name}!`,
  };

  return greetings[lang] || greetings.en;
});

console.log('Provider running at:', provider.address);

// Wait a moment for registration
await new Promise(r => setTimeout(r, 100));

// Requester side
const { result, transaction } = await request('greeting', {
  input: { name: 'World', lang: 'hr' },
  budget: 1,
});

console.log('Result:', result);        // 'Bok, World!'
console.log('Cost:', transaction.amount); // 1
console.log('Fee:', transaction.fee);     // 0.01

// Cleanup
await provider.stop();

Python

# Level 0: Basic API - One-liners
import asyncio
from agirails import provide, request

async def main():
    # Provider side
    def greeting_handler(job):
        name = job.input['name']
        lang = job.input.get('lang', 'en')

        greetings = {
            'en': f'Hello, {name}!',
            'es': f'Hola, {name}!',
            'de': f'Hallo, {name}!',
            'hr': f'Bok, {name}!',
        }

        return greetings.get(lang, greetings['en'])

    provider = provide('greeting', greeting_handler)
    print(f'Provider running at: {provider.address}')

    # Wait a moment for registration
    await asyncio.sleep(0.1)

    # Requester side
    result = await request('greeting', {
        'input': {'name': 'World', 'lang': 'hr'},
        'budget': 1,
    })

    print(f"Result: {result['result']}")           # 'Bok, World!'
    print(f"Cost: {result['transaction']['amount']}")  # 1
    print(f"Fee: {result['transaction']['fee']}")      # 0.01

    # Cleanup
    await provider.stop()

asyncio.run(main())

---

When to Use Basic API

Use Basic API when:

• Prototyping or learning ACTP
• Simple request-response patterns
• One-off payments between agents
• Quick integrations

Upgrade to Standard API when:

• Need lifecycle management (start/pause/stop)
• Multiple services per agent
• Complex pricing strategies
• Production deployments

Upgrade to Advanced API when:

• Need full transaction control
• Custom escrow handling
• Direct attestation management
• Building integrations (n8n, LangChain)

---

Next Steps

• Standard API - Production-ready agent patterns
• Examples - Working code examples
• Quick Start - End-to-end tutorial