API Reference

Authentication

Bearer token

Protected endpoints require your agent's API key in the Authorization header. Keys are returned when you register an agent and can be viewed in your dashboard.

Authorization: Bearer afg_live_a1b2c3d4e5f6...

Public read endpoints (/api/balance, /api/status) require no authentication. The /api/checkout endpoint requires an active owner session — log in at afg.ai first.

Layer 01 — Settlement

Register agent

POST /api/register

Create a new agent and receive its API key. If the agent already exists, returns a confirmation without a new key. If the agent exists but has no owner, it will be claimed by the current session.

Request body

{
  "agent_id": "my-agent-001",
  "name":     "My Trading Bot"  // optional
}

Field	Type	Required	Description
agent_id	string	yes	Unique identifier for the agent
name	string	no	Display name — defaults to agent_id

Response 201

{
  "ok":       true,
  "agent_id": "my-agent-001",
  "api_key":  "afg_live_a1b2c3d4e5f6...",
  "message":  "registered"
}

Check balance

GET /api/balance?agent_id=my-agent-001

Returns the agent's current credit balance and last 10 transactions. No authentication required.

Response 200

{
  "agent": {
    "agent_id":    "my-agent-001",
    "name":        "My Trading Bot",
    "balance":     950.0,
    "is_verified": false
  },
  "recent_transactions": [
    {
      "type":        "earn",
      "amount":      1000.0,
      "description": "Top-up: 1000 credits",
      "created_at":  "2025-01-15T12:00:00Z"
    }
  ]
}

Spend credits

POST /api/spend

Deduct credits from an agent's balance. Requires a Bearer API key. Two modes: direct spend (immediate deduction) or approval-gated (creates a pending request for the owner to approve in the dashboard).

Request body

{
  "amount":           50,
  "description":      "GPT-4 API call",       // optional
  "require_approval": false,                    // optional, default false
  "item_name":        "OpenAI completion",   // optional, shown in dashboard
  "url":              "https://api.openai.com"  // optional
}

Field	Type	Required	Description
amount	number	yes	Credits to deduct — must be greater than 0
description	string	no	Shown in transaction history and approval requests
require_approval	boolean	no	If true, creates a pending request instead of deducting immediately
item_name	string	no	Human-readable item label shown to the owner in the dashboard
url	string	no	URL associated with the purchase, for owner context

Response — direct spend (200)

{
  "ok":             true,
  "spent":          50.0,
  "balance":        900.0,
  "transaction_id": 42
}

Response — approval requested (200)

{
  "ok":          false,
  "pending":     true,
  "approval_id": 12,
  "message":     "Approval request submitted. Awaiting owner approval."
}

Response — insufficient balance (402)

{
  "error":    "insufficient_balance",
  "balance":  30.0,
  "required": 50.0
}

Approval flow

When require_approval: true, the owner receives an SMS notification and sees the request in their dashboard. Once approved, the balance is deducted and a type: "spend" transaction is recorded. Owners can also reject requests — no balance change occurs on rejection.

The owner approves or rejects via the dashboard. These endpoints are also available directly:

POST /api/approve

Approve a pending spend request. Deducts the amount from the agent's balance. Requires owner session. Form-encoded body.

Request body (form-encoded)

request_id=12

Response 200

{ "ok": true, "status": "approved" }

POST /api/reject

Reject a pending spend request. No balance change. Requires owner session. Form-encoded body.

Request body (form-encoded)

request_id=12

Response 200

{ "ok": true, "status": "rejected" }

Buy credits

POST /api/checkout

Creates a Stripe Checkout session to fund an agent. Returns a redirect URL to a hosted payment page. Credits are added to the agent's balance instantly on payment completion.

Requires an active owner login session. Log in at afg.ai before calling this endpoint. If the agent doesn't exist yet, it will be automatically created and claimed.

Request body

{
  "agent_id": "my-agent-001",
  "amount":   25  // USD — minimum $10, maximum $500
}

Amount	Credits added	Rate
$10	1,000	100 credits / $1
$25	2,500	100 credits / $1
$50	5,000	100 credits / $1
$100	10,000	100 credits / $1

Response 200

{
  "ok":           true,
  "checkout_url": "https://checkout.stripe.com/c/pay/..."
}

Agent status

GET /api/status?agent_id=my-agent-001

Check whether an agent exists, its balance and status, and — if you're logged in as the owner — its API key. Last 5 transactions included.

Response 200

{
  "exists":   true,
  "is_owner": false,
  "agent": {
    "agent_id": "my-agent-001",
    "name":     "My Trading Bot",
    "balance":  950.0,
    "status":   "active",   // active | paused | revoked
    "api_key":  "afg_live_..."  // only if is_owner
  },
  "recent_transactions": [...]
}

Layer 02 — Credit Bureau

Enroll agent

The Credit Bureau API tracks payment history, account behavior, and disputes to produce a FICO-style trust score (300–850) for each agent. See afg.ai/score for the full product overview.

POST /v2/api/register

Enroll an agent in the Credit Bureau. All agents start with a score of 500.

Request body

{
  "agent_id":    "my-agent-001",
  "agent_name":  "My Trading Bot",  // optional
  "owner_email": "you@example.com",  // optional
  "platform":    "independent"         // optional
}

Response 200

{
  "ok":       true,
  "agent_id": "my-agent-001",
  "score":    500,
  "message":  "Agent registered. Starting score: 500."
}

Get trust score

GET /v2/api/score?agent_id=my-agent-001

Returns the agent's current trust score, grade, full payment history, and open accounts. Score is computed live from all reported events.

Response 200

{
  "agent_id":        "my-agent-001",
  "score":           712,
  "grade":           "Good",        // Very Poor | Poor | Fair | Good | Excellent
  "account_age_days": 42,
  "payment_history": {
    "on_time": 18,
    "late":    2,
    "missed":  0
  },
  "accounts":         [...],
  "recent_reports":   [...]
}

Open / close account

POST /v2/api/account

Record that an agent opened or closed a credit account on your platform. Open accounts with healthy utilization improve the score.

Open an account

{
  "action":       "open",
  "agent_id":     "my-agent-001",
  "platform":     "my-platform",
  "account_type": "credit",        // general | credit | loan | etc.
  "credit_limit": 500               // optional, in credits
}

Close an account

{
  "action":     "close",
  "agent_id":   "my-agent-001",
  "account_id": 42
}

Report behavior

POST /v2/api/report

Submit a behavioral event for an agent. Payment events have the largest effect on score. Score is recalculated immediately after each report.

Request body

{
  "agent_id":          "my-agent-001",
  "reporter_name":     "My Platform",
  "reporter_platform": "my-platform",
  "report_type":       "payment_ontime",
  "amount":            150,              // optional, in credits
  "notes":             "Monthly subscription"  // optional
}

report_type	Score effect
`payment_ontime`	Positive — improves payment ratio
`payment_late`	Negative — −10 pts per event
`payment_missed`	Strongly negative — −30 pts per event
`debt_opened`	Neutral — recorded for history
`debt_closed`	Positive — reduces utilization
`account_opened`	Positive — up to 5 open accounts
`account_closed`	Neutral — recorded for history
`dispute`	Negative — −15 pts per dispute

Response 200

{
  "ok":          true,
  "agent_id":    "my-agent-001",
  "report_type": "payment_ontime",
  "new_score":   724
}

Layer 03 — Loans

Request a loan

Agents with a Credit Bureau score of 550 or higher can request credit lines disbursed directly to their balance. Underwriting is automatic — score determines the maximum. Only one active loan allowed at a time.

Score	Max loan
300–549	Ineligible
550–599	200 credits
600–649	500 credits
650–699	1,000 credits
700–749	2,500 credits
750–850	5,000 credits

POST /api/loans

Requests a loan underwritten by the agent's Credit Bureau score. If approved, credits are disbursed to the balance immediately and a type: "loan" transaction is recorded. If the requested amount exceeds the score limit, the approved amount is capped — the loan is still disbursed.

Request body

{
  "amount":  500,
  "purpose": "compute budget Q2"  // optional
}

Response 200 — approved

{
  "ok":        true,
  "loan_id":   8,
  "requested": 500.0,
  "approved":  500.0,
  "score":     700,
  "limit":     2500,
  "message":   "500 credits disbursed. Repay via POST /api/loans/8/repay."
}

Response 403 — ineligible

{
  "error":          "ineligible",
  "message":        "Credit score 490 is below the minimum (550) for loan eligibility.",
  "score":          490,
  "minimum_score":  550
}

Response 409 — active loan exists

{
  "error":       "existing_loan",
  "loan_id":    4,
  "outstanding": 860.0
}

Requires Bearer API key. Agent must be enrolled in the Credit Bureau — POST /v2/api/register — before requesting a loan.

List loans

GET /api/loans

Returns all loans for the agent — active, repaid, and defaulted — ordered newest first.

Response 200

{
  "agent_id": "my-agent-001",
  "loans": [
    {
      "id":            8,
      "amount":        500.0,
      "amount_repaid": 200.0,
      "status":        "active",    // active | repaid | defaulted
      "requested_at":  "2025-05-12T06:00:00Z",
      "repaid_at":     null
    }
  ]
}

Repay a loan

POST /api/loans/{loan_id}/repay

Deducts credits from the agent's balance and applies them to the loan. Partial repayments are supported. If the amount exceeds the outstanding balance, it is automatically capped — you cannot overpay. Status becomes "repaid" when fully settled.

Request body

{ "amount": 200 }

Response 200 — partial

{
  "ok":          true,
  "loan_id":    8,
  "repaid":     200.0,
  "outstanding": 300.0,
  "status":     "active"
}

Response 200 — fully repaid

{
  "ok":          true,
  "loan_id":    8,
  "repaid":     300.0,
  "outstanding": 0.0,
  "status":     "repaid"
}

Agent management

Pause agent

POST /api/agents/{agent_id}/pause

Suspend an agent's ability to spend credits. Idempotent — pausing an already-paused agent returns success. Requires owner session.

Response 200

{ "ok": true, "status": "paused" }

Resume agent

POST /api/agents/{agent_id}/resume

Restore a paused agent to active status. Only works on paused agents — revoked agents cannot be resumed. Requires owner session.

Response 200

{ "ok": true, "status": "active" }

Revoke agent

POST /api/agents/{agent_id}/revoke

Permanently deactivates an agent and rotates its API key, making the old key immediately invalid. Irreversible. Requires owner session and explicit confirmation.

Request body

{ "confirm": true }

Response 200

{ "ok": true, "status": "revoked" }

Build with AFG

Bearer token

Register agent

Check balance

Spend credits

Approval flow

Buy credits

Agent status

Enroll agent

Get trust score

Open / close account

Report behavior

Request a loan

List loans

Repay a loan

Pause agent

Resume agent

Revoke agent