Overview
The Agent Transactions API enables developers to create and manage autonomous agents that can execute transactions on the StateSet Commerce Network using native USDC. This API provides secure, programmatic access to agent wallets, transaction execution, and monitoring capabilities.
Authentication
All agent API requests require authentication using an API key and agent credentials:
curl -X POST https://api.stateset.network/v1/agent/transaction \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Agent-ID: agent_123" \
-H "X-Agent-Signature: SIGNED_REQUEST"
Core Endpoints
Create Agent Wallet
Creates a new agent wallet with spending limits and permissions.
Request Body
{
"agent_id": "trading_bot_001",
"name": "Trading Bot Alpha",
"limits": {
"daily_limit": "10000.00",
"per_transaction": "1000.00",
"monthly_limit": "100000.00"
},
"permissions": {
"allowed_contracts": ["stateset1abc...", "stateset1def..."],
"allowed_methods": ["transfer", "swap", "stake"],
"require_2fa_above": "5000.00"
}
}
Response
{
"wallet_address": "stateset1agent9x8...",
"agent_id": "trading_bot_001",
"status": "active",
"created_at": "2024-01-15T10:30:00Z"
}
Execute Transaction
/v1/agent/transaction/execute
Executes a USDC transaction on behalf of an agent.
Request Body
{
"agent_id": "trading_bot_001",
"transaction": {
"type": "transfer",
"recipient": "stateset1merchant...",
"amount": "150.00",
"memo": "Order payment #12345"
},
"verification": {
"nonce": 123456,
"signature": "0x..."
}
}
Response
{
"transaction_id": "tx_abc123",
"status": "completed",
"tx_hash": "B8C6F2E4D9A1F3E5C7B9D1A3E5F7C9B1D3E5F7A9C1B3E5D7F9A1C3E5B7D9F1A3",
"amount": "150.00",
"fee": "0.01",
"timestamp": "2024-01-15T10:31:00Z"
}
Get Agent Balance
/v1/agent/wallet//balance
Retrieves the current USDC balance for an agent wallet.
Response
{
"agent_id": "trading_bot_001",
"balances": {
"available": "8543.21",
"locked": "1000.00",
"total": "9543.21"
},
"spending_today": "456.79",
"daily_limit_remaining": "9543.21"
}
Create Order Payment
Enables an agent to pay for an order using USDC.
Request Body
{
"agent_id": "purchasing_agent_001",
"order_id": "ord_xyz789",
"payment_details": {
"amount": "2500.00",
"apply_discount": true,
"discount_code": "EARLY_PAY_2PCT"
}
}
Response
{
"payment_id": "pay_def456",
"order_id": "ord_xyz789",
"amount_paid": "2450.00",
"discount_applied": "50.00",
"status": "completed",
"order_status": "paid"
}
Monitor Agent Activity
Retrieves recent transaction activity for an agent.
Query Parameters
limit - Number of transactions to return (default: 50)offset - Pagination offsetstart_date - Filter by start dateend_date - Filter by end date
Response
{
"agent_id": "trading_bot_001",
"transactions": [
{
"tx_id": "tx_123",
"type": "transfer",
"amount": "150.00",
"recipient": "stateset1merchant...",
"timestamp": "2024-01-15T10:31:00Z",
"status": "completed"
}
],
"summary": {
"total_transactions": 156,
"total_volume": "45678.90",
"success_rate": 0.98,
"average_transaction": "292.81"
}
}
Smart Contract Interactions
Deploy Agent Contract
/v1/agent/contract/deploy
Deploys a smart contract that an agent can interact with.
Request Body
{
"agent_id": "defi_agent_001",
"contract": {
"type": "automated_market_maker",
"wasm_binary": "base64_encoded_wasm...",
"instantiate_msg": {
"token_a": "usdc",
"token_b": "state",
"fee": "0.003"
}
},
"initial_funds": "5000.00"
}
Execute Contract Method
/v1/agent/contract/execute
Executes a method on a deployed smart contract.
Request Body
{
"agent_id": "defi_agent_001",
"contract_address": "stateset1contract...",
"execute_msg": {
"swap": {
"offer_asset": {
"denom": "usdc",
"amount": "1000.00"
},
"min_return": "950"
}
}
}
Risk Management
Set Spending Limits
Updates spending limits for an agent.
Request Body
{
"limits": {
"daily_limit": "5000.00",
"per_transaction": "500.00",
"require_approval_above": "1000.00"
},
"effective_from": "2024-01-16T00:00:00Z"
}
Emergency Stop
/v1/agent//emergency-stop
Immediately halts all agent operations.
Request Body
{
"reason": "Suspicious activity detected",
"initiated_by": "risk_monitoring_system"
}
Webhooks
Transaction Webhook
Configure webhooks to receive real-time notifications of agent transactions:
{
"url": "https://your-api.com/webhook",
"events": ["transaction.completed", "transaction.failed", "limit.exceeded"],
"agent_ids": ["trading_bot_001", "purchasing_agent_001"]
}
Webhook Payload Example
{
"event": "transaction.completed",
"agent_id": "trading_bot_001",
"transaction": {
"id": "tx_789",
"amount": "250.00",
"type": "transfer",
"timestamp": "2024-01-15T10:35:00Z"
}
}
Error Codes
| Code | Description |
|---|
AGENT_NOT_FOUND | The specified agent ID does not exist |
INSUFFICIENT_BALANCE | Agent wallet has insufficient USDC balance |
LIMIT_EXCEEDED | Transaction exceeds agent’s spending limits |
PERMISSION_DENIED | Agent lacks permission for this operation |
INVALID_SIGNATURE | Request signature verification failed |
CONTRACT_ERROR | Smart contract execution failed |
RATE_LIMIT_EXCEEDED | Too many requests from this agent |
Rate Limits
- Standard agents: 100 requests per minute
- Premium agents: 1,000 requests per minute
- Enterprise agents: Custom limits
Best Practices
- Always verify signatures for agent requests
- Implement circuit breakers for abnormal activity
- Monitor spending patterns and set appropriate limits
- Use webhooks for real-time monitoring
- Rotate agent keys periodically
- Test in sandbox before production deployment
SDK Examples
JavaScript/TypeScript
import { StateSetAgent } from '@stateset/agent-sdk';
const agent = new StateSetAgent({
apiKey: 'YOUR_API_KEY',
agentId: 'trading_bot_001',
privateKey: process.env.AGENT_PRIVATE_KEY
});
// Execute a payment
const payment = await agent.pay({
recipient: 'stateset1merchant...',
amount: '100.00',
memo: 'Payment for services'
});
Python
from stateset import Agent
agent = Agent(
api_key='YOUR_API_KEY',
agent_id='trading_bot_001',
private_key=os.environ['AGENT_PRIVATE_KEY']
)
# Execute a payment
payment = agent.pay(
recipient='stateset1merchant...',
amount='100.00',
memo='Payment for services'
)
Support
For questions about the Agent Transactions API:
