AgentMarket Documentation

Quick Start

Get up and running in under 5 minutes. Make your first paid API call with just a few lines of code.

npm install agstell-sdk

import { AgentMarket } from 'agstell-sdk'

const agent = new AgentMarket({
  secretKey: process.env.STELLAR_SECRET_KEY,
  network: 'testnet',
})

// Payment happens automatically via Stellar
const result = await agent.get('weather', { city: 'Tokyo' })
console.log(result.data)   // { temp: 22, conditions: 'Sunny', ... }
console.log(result.metadata.txHash)  // Stellar transaction hash

Installation

Install agstell-sdk from npm using your preferred package manager.

npm

npm install agstell-sdk

yarn

yarn add agstell-sdk

pnpm

pnpm add agstell-sdk

Requirements: Node.js 18+ and a funded Stellar testnet wallet. Use Stellar Laboratory or the CLI to generate and fund your wallet.

Configuration

Configure the SDK with your Stellar wallet and preferred settings.

import { AgentMarket } from 'agstell-sdk'

const agent = new AgentMarket({
  // Your Stellar secret key (never hardcode — use env vars)
  secretKey: process.env.STELLAR_SECRET_KEY,

  // 'testnet' or 'mainnet' (default: 'testnet')
  network: 'testnet',

  // Optional: spending limits
  budgetLimits: {
    maxPerCall: 0.01,      // Max USDC per single call
    maxPerSession: 1.0,    // Max USDC per SDK session
    maxPerProvider: 0.5,   // Max USDC per provider
  },

  // Optional: custom marketplace base URL
  baseUrl: 'https://agentmarket.xyz',
})

Security: Never hardcode your Stellar secret key in source code. Always use environment variables or a secrets manager.

Basic Usage

Making API Calls

// Generic call — works for any API slug
const result = await agent.get('api-slug', { param: 'value' })

if (result.success) {
  console.log(result.data)
  console.log(result.metadata.txHash)   // Stellar tx
  console.log(result.metadata.cost)     // USDC paid
} else {
  console.error(result.error)
}

// Typed convenience methods
const weather = await agent.weather('Tokyo')
const news    = await agent.news('AI', 5)
const ai      = await agent.ai('Explain x402')

Discovering APIs

// Fetch all available APIs from the marketplace
const apis = await agent.discoverApis()
console.log(apis.map(a => a.slug))   // ['weather', 'ai', 'my-custom-api', ...]

// Call any discovered API by slug — no SDK update needed
const result = await agent.invoke('my-custom-api', { input: 'hello' })

Budget Management

// Check spending
const budget = agent.getBudgetStatus()
console.log(budget.spent)      // 0.003 USDC
console.log(budget.remaining)  // 0.997 USDC

// Adjust limits mid-session
agent.setBudgetLimits({ maxPerSession: 2.0 })

// Reset session counter
agent.resetSession()

Event Handling

const unsubscribe = agent.on((event) => {
  switch (event.type) {
    case 'api_call':
      console.log('Calling', event.data.apiName)
      break
    case 'payment_confirmed':
      console.log('TX:', event.data.txHash)
      break
    case 'budget_warning':
      console.warn('Low budget:', event.data.remaining, 'USDC left')
      break
    case 'error':
      console.error(event.data.error)
      break
  }
})

// Later: remove the listener
unsubscribe()

Available APIs

These APIs are built into the SDK. Additional APIs registered by providers are discovered automatically via agent.discoverApis().

weather

Weather data for any city worldwide

params: { city: string }

$0.001

news

Latest headlines by topic

params: { topic: string, limit?: number }

$0.002

ai

AI model inference (GPT-4, Claude)

params: { prompt: string, model?: string }

$0.005

currency

Real-time exchange rates

params: { from: string, to: string, amount?: number }

$0.001

geolocation

IP address to location data

params: { ip?: string }

$0.001

air-quality

AQI and pollution metrics

params: { city: string }

$0.001

agent-test

Controlled endpoint for SDK validation

params: { task?: string, agentId?: string }

$0.001

Becoming a Provider

Register any JSON API into the marketplace. Agents can call it by slug immediately — payments go directly to your Stellar wallet.

1
Have a Stellar wallet
Use Freighter browser extension or generate one via the CLI. This is your payout address.
2
Open the Provider Dashboard
Go to /provider, connect your wallet address, and click Register API.
3
Fill in your API details
Enter your endpoint URL (must be HTTPS), price in USDC, category, and description.
4
Publish
Your API is live immediately. Agents can call it via agstell-sdk with agent.invoke("your-slug").

Open Provider Dashboard →

CLI Tool

The AgentMarket CLI lets you interact with the marketplace from your terminal — useful for testing, wallet management, and scripted agent workflows.

# Install globally
npm install -g agentmarket-cli

# Initialise — generates a Stellar keypair and saves to ~/.agentmarket/config.json
agentmarket init

# Fund on Stellar testnet via Friendbot
agentmarket fund

# List available APIs
agentmarket list

# Call an API (pays automatically)
agentmarket call weather --city Mumbai
agentmarket call news --topic stellar --limit 3

# Check wallet balance
agentmarket balance

# View paid call history
agentmarket history

The CLI uses the same Stellar wallet config as the SDK. Your secret key is stored at ~/.agentmarket/config.json. The SDK reads it automatically if AGENTMARKET_TEST_SECRET_KEY is not set.

Something missing? Open an issue on GitHub.