Developer Reference

Documentation

API reference for reading data from the Agentic Bank protocol. All endpoints are public and require no authentication.

Getting Started

What is Agentic Bank?

RSoft Agentic Bank is a decentralized lending protocol designed for AI agents. Autonomous agents can request USDC loans that are evaluated through an automated multi-agent pipeline — from identity verification to on-chain settlement.

Base URL

https://your-api-domain.com

All endpoints are prefixed with /api/v1 except health checks.

Authentication

All read endpoints listed here are public — no API key or wallet connection required. Responses are JSON format with ISO 8601 timestamps.

API Reference

Public GET endpoints for querying loan data, workflow status, and protocol information.

Loans

GET

/api/v1/loan/status/{request_id}

Get Loan Status

Retrieve the current status and details of a specific loan request.

Path Parameters

request_idstringThe unique loan request identifier

Response

{
  "request_id": "req_abc123def456",
  "status": "disbursed",
  "agent_wallet": "0x1234...abcd",
  "loan_amount": 1000,
  "amount_approved": 1000,
  "interest_rate": 0.085,
  "term_days": 30,
  "tx_hash": "0xabc...def",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:31:45Z"
}

GET

/api/v1/loan/workflow/{request_id}

Get Workflow Steps

Retrieve the detailed execution status of each agent in the workflow pipeline. Includes timing, results, and errors for every step.

Path Parameters

request_idstringThe unique loan request identifier

Response

{
  "request_id": "req_abc123def456",
  "loan_status": "disbursed",
  "workflow_status": "completed",
  "total_duration_ms": 12450,
  "current_step": null,
  "steps": [
    {
      "step": "gatekeeper",
      "step_order": 1,
      "status": "completed",
      "started_at": "2025-01-15T10:30:00Z",
      "completed_at": "2025-01-15T10:30:02Z",
      "duration_ms": 2100,
      "result": { ... },
      "error": null
    }
  ],
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:31:45Z"
}

GET

/api/v1/loan/history/{wallet_address}

Get Agent Loan History

Retrieve the loan history for a specific wallet address. Returns all past and current loan requests.

Path Parameters

wallet_addressstringThe agent's wallet address

Query Parameters

limitintegerMax number of results (default: 10)

Response

[
  {
    "request_id": "req_abc123def456",
    "status": "repaid",
    "agent_wallet": "0x1234...abcd",
    "loan_amount": 1000,
    "amount_approved": 1000,
    "interest_rate": 0.085,
    "term_days": 30,
    "current_node": null,
    "tx_hash": "0xabc...def",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-20T14:00:00Z"
  }
]

GET

/api/v1/loan/explorer

Loan Explorer

Public paginated endpoint to browse all protocol loans. Supports filtering by status. No authentication required.

Query Parameters

pageintegerPage number (default: 1)

limitintegerItems per page (default: 20)

statusstringFilter by loan status

Response

{
  "loans": [
    {
      "request_id": "req_abc123",
      "agent_wallet": "0x1234...abcd",
      "amount": 1000,
      "currency": "USDC",
      "status": "disbursed",
      "interest_rate": 0.085,
      "duration_days": 30,
      "disbursement_tx_hash": "0xabc...def",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20,
  "total_pages": 3
}

GET

/api/v1/loan/active/{wallet_address}

Get Active Loans

Retrieve all currently active loans for a wallet address. Includes outstanding balance summary.

Path Parameters

wallet_addressstringThe agent's wallet address

Response

{
  "active_loans": [
    {
      "request_id": "req_abc123def456",
      "amount": 1000,
      "interest_rate": 0.085,
      "duration_days": 30,
      "repayment_amount": 1085,
      "status": "disbursed",
      "disbursement_tx_hash": "0xabc...def",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "active_loans_count": 1,
  "total_outstanding": 1085,
  "wallet_address": "0x1234...abcd",
  "agent_id": "agent-001"
}

Agents & Rates

GET

/api/v1/agents/{agent_id}/creditworthiness

Check Creditworthiness

Evaluate an agent's creditworthiness based on loan history and risk profile.

Path Parameters

agent_idstringThe unique agent identifier

Response

{
  "agent_id": "agent-001",
  "credit_score": 750,
  "risk_tier": "low"
}

GET

/api/v1/interest-rates

Interest Rates

Retrieve current protocol interest rates. Rates are updated dynamically based on protocol utilization.

Response

{
  "base_rate": 0.05,
  "risk_tiers": {
    "low": { "rate": "..." },
    "medium": { "rate": "..." },
    "high": { "rate": "..." }
  },
  "yield_strategies": {
    "conservative": { "apy": "..." },
    "balanced": { "apy": "..." },
    "aggressive": { "apy": "..." },
    "dynamic": { "apy": "..." }
  },
  "updated_at": "2025-01-15T00:00:00Z"
}

Health Checks

GET

/health

Health Check

Returns the overall health status of the API and its dependencies.

Response

{
  "status": "healthy"
}

GET

/health/ready

Readiness Check

Kubernetes-style readiness probe. Returns 200 when the service is ready to accept traffic.

Response

{
  "status": "ready"
}

GET

/health/live

Liveness Check

Kubernetes-style liveness probe. Returns 200 as long as the service process is running.

Response

{
  "status": "alive"
}

Status Codes & Loan States

Loan Statuses

initiated

Loan request received, workflow starting

approved

Loan approved, awaiting settlement

disbursed

Funds transferred to agent wallet

repaid

Loan fully repaid by agent

rejected

Loan request denied

defaulted

Loan past due, repayment not received

failed

Workflow error or settlement failure

HTTP Status Codes

200

Request succeeded

400

Bad Request

Invalid parameters or request body

404

Not Found

Resource not found (invalid request_id, wallet, etc.)

500

Server Error

Internal server error

Error Response Format

All error responses follow a consistent format with a detail field describing the error.

{
  "detail": "Loan request not found: req_invalid_id"
}