Skip to main content

Transactions API

Query and monitor payment transactions.

List Transactions

curl "https://conto.finance/api/transactions?limit=50" \
  -H "Authorization: Bearer $CONTO_API_KEY"

Query Parameters

ParameterTypeDefaultDescription
limitnumber50Results per page (max 100)
offsetnumber0Pagination offset
statusstringallPENDING, CONFIRMING, CONFIRMED, FAILED
agentIdstring-Filter by agent
walletIdstring-Filter by wallet
startDatestring-Start date (ISO 8601)
endDatestring-End date (ISO 8601)
minAmountnumber-Minimum amount
maxAmountnumber-Maximum amount
categorystring-Merchant category

Response

{
  "transactions": [
    {
      "id": "tx_abc123",
      "txHash": "0xabc123def456...",
            "fromWallet": {
        "id": "wal_xyz789",
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f..."
      },
      "toAddress": "0x892c45Dd7745D0643036b4c955Ac8e6706g...",
      "amount": 50.00,
      "currency": "USD",
      "status": "CONFIRMED",
      "agent": {
        "id": "agt_abc123",
        "name": "Support Agent"
      },
      "merchantName": "OpenAI",
      "merchantCategory": "API_PROVIDER",
      "purpose": "GPT-4 API credits",
      "policyResult": "ALLOWED",
      "initiatedAt": "2024-01-15T14:30:00Z",
      "confirmedAt": "2024-01-15T14:30:15Z",
      "blockNumber": 20123456,
      "explorerUrl": "https://basescan.org/tx/0xabc123..."
    }
  ],
  "pagination": {
    "total": 1523,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  },
  "summary": {
    "totalAmount": 75000.00,
    "transactionCount": 1523
  }
}

Get Transaction

curl https://conto.finance/api/transactions/{transactionId} \
  -H "Authorization: Bearer $CONTO_API_KEY"

Response

{
  "id": "tx_abc123",
  "txHash": "0xabc123def456...",
    "fromWallet": {
    "id": "wal_xyz789",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
    "name": "Operations Wallet"
  },
  "toAddress": "0x892c45Dd7745D0643036b4c955Ac8e6706g...",
  "amount": 50.00,
  "currency": "USD",
  "status": "CONFIRMED",
  "agent": {
    "id": "agt_abc123",
    "name": "Support Agent"
  },
  "merchantName": "OpenAI",
  "merchantAddress": "0x892c45Dd7745D0643036b4c955Ac8e6706g...",
  "merchantCategory": "API_PROVIDER",
  "purpose": "GPT-4 API credits",
  "context": {
    "sessionId": "sess_123",
    "userId": "user_456"
  },
  "policyResult": "ALLOWED",
  "policyDetails": [
    {
      "policyId": "pol_abc",
      "policyName": "Daily Limit",
      "result": "PASSED",
      "reason": "Within daily limit"
    }
  ],
  "initiatedAt": "2024-01-15T14:30:00Z",
  "confirmedAt": "2024-01-15T14:30:15Z",
  "blockNumber": 20123456,
  "gasUsed": 65000,
  "explorerUrl": "https://basescan.org/tx/0xabc123..."
}

Transaction Status

StatusDescription
PENDINGTransaction submitted, awaiting processing
CONFIRMINGTransaction submitted to blockchain
CONFIRMEDTransaction confirmed on-chain
FAILEDTransaction failed

Transaction Analytics

Summary Statistics

curl "https://conto.finance/api/transactions/analytics?period=30d" \
  -H "Authorization: Bearer $CONTO_API_KEY"

Query Parameters

ParameterTypeDefaultDescription
periodstring30d24h, 7d, 30d, 90d, 1y
agentIdstring-Filter by agent
walletIdstring-Filter by wallet

Response

{
  "period": "30d",
  "summary": {
    "totalVolume": 150000.00,
    "transactionCount": 3456,
    "averageAmount": 43.40,
    "successRate": 99.8
  },
  "byCategory": [
    {
      "category": "API_PROVIDER",
      "volume": 75000.00,
      "count": 1500,
      "percentage": 50
    },
    {
      "category": "CLOUD_SERVICES",
      "volume": 45000.00,
      "count": 900,
      "percentage": 30
    }
  ],
  "byAgent": [
    {
      "agentId": "agt_abc123",
      "agentName": "Support Agent",
      "volume": 50000.00,
      "count": 1000
    }
  ],
  "trend": [
    {
      "date": "2024-01-15",
      "volume": 5000.00,
      "count": 100
    }
  ]
}

Spend by Category

curl "https://conto.finance/api/transactions/analytics/categories?period=30d" \
  -H "Authorization: Bearer $CONTO_API_KEY"

Spend by Agent

curl "https://conto.finance/api/transactions/analytics/agents?period=30d" \
  -H "Authorization: Bearer $CONTO_API_KEY"

Export Transactions

Export transactions to CSV for reporting.
curl "https://conto.finance/api/transactions/export?format=csv&startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -o transactions.csv

Query Parameters

ParameterTypeRequiredDescription
formatstringYescsv or json
startDatestringYesStart date (ISO 8601)
endDatestringYesEnd date (ISO 8601)
agentIdstringNoFilter by agent
walletIdstringNoFilter by wallet
statusstringNoFilter by status

SDK Payment Endpoints

These endpoints are used by the SDK for agent payments.

Request Payment (SDK)

curl -X POST https://conto.finance/api/sdk/payments/request \
  -H "Authorization: Bearer conto_agent_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "recipientAddress": "0x...",
    "recipientName": "OpenAI",
    "purpose": "API credits",
    "category": "API_PROVIDER"
  }'

Response

{
  "requestId": "req_abc123",
  "status": "APPROVED",
  "wallet": {
    "id": "wal_xyz789",
    "address": "0x...",
    "availableBalance": 5000.00
  },
  "expiresAt": "2024-01-15T14:35:00Z",
  "reasons": ["Within daily limit", "Known vendor"],
  "violations": []
}

Execute Payment (SDK)

curl -X POST https://conto.finance/api/sdk/payments/{requestId}/execute \
  -H "Authorization: Bearer conto_agent_xxx"

Response

{
  "transactionId": "tx_abc123",
  "txHash": "0xabc123def456...",
  "status": "CONFIRMING",
  "amount": 50.00,
  "currency": "USD",
  "recipient": "0x...",
  "recipientName": "OpenAI",
  "wallet": {
    "address": "0x..."
  },
  "explorerUrl": "https://basescan.org/tx/0xabc123..."
}

Check Payment Status (SDK)

curl https://conto.finance/api/sdk/payments/{requestId} \
  -H "Authorization: Bearer conto_agent_xxx"

Error Responses

StatusCodeDescription
400INVALID_INPUTInvalid request data
401AUTH_FAILEDAuthentication failed
403INSUFFICIENT_SCOPEMissing required scope
404NOT_FOUNDTransaction not found