API Documents

Localcredit provides a simple, powerful API for querying scores, reporting outcomes, and managing subscriptions. The API is available via both REST (for web/mobile/Telegram Mini Apps) and on-chain oracle calls (for smart contracts).Base URL (REST): https://api.localcredit.org/v1AuthenticationAll requests require authentication to prevent abuse and ensure billing.Method: API Key + Signed Message

1. Get Your API Key Sign up at docs.localcredit.org/dashboard → generate a key instantly (linked to your developer account).

2. For Each Request

   • Include header: Authorization: Bearer <your_api_key>

   • Include header: X-Signature: <signed_message>

   • The signed message is a wallet signature of the request payload + timestamp (prevents replay attacks).

JavaScript Example (using TON wallet)javascript

const timestamp = Date.now();
const payload = JSON.stringify({ timestamp, path: '/score', body: requestBody });

const signature = await tonWallet.signMessage(payload);

fetch('https://api.localcredit.org/v1/score', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'X-Signature': signature,
    'Content-Type': 'application/json',
    'X-Timestamp': timestamp
  },
  body: JSON.stringify({ proof: userProof })
});

On-chain queries use standard oracle authentication (pay fee in $CREDIT via contract call).EndpointsGET /score Fetch a user's current score and related data.Request (POST for body security):json

{
  "proof": "0xzkp..."   // User's ZK proof hash or signed proof bundle
}

Response:json

{
  "score": 82,
  "riskTier": "Low",
  "creditLimitUsd": 5200,
  "breakdown": {
    "repayment": 33,
    "consistency": 18,
    "identity": 16,
    "continuity": 15,
    "riskDeductions": -0
  },
  "proofValid": true,
  "timestamp": 1736100000
}

POST /reportOutcome Report a loan outcome to help improve the shared model (anonymized).Request:json

{
  "loanHash": "0x123...",
  "outcome": "repaid",        // or "default" or "partial"
  "amountUsd": 2500,
  "timestamp": 1736100000,
  "details": {                // optional extra metadata
    "daysLate": 0
  }
}

Response:json

{
  "success": true,
  "reportId": "rep_abc123"
}

POST /subscribe Create or manage a subscription for higher volume / lower costs.Request:json

{
  "plan": "pro",              // "basic", "pro", "enterprise"
  "stakeAmount": 10000        // $CREDIT to stake for the period
}

Response:json

{
  "subscriptionId": "sub_123",
  "status": "active",
  "queriesRemaining": 100000,
  "expires": 1742000000
}

Rate Limits & Billing

All usage is paid in $CREDIT (deducted automatically from your linked wallet).

Plan	Monthly Cost ($CREDIT)	Queries Included	Cost per Extra Query	Rate Limit (queries/min)
Free / Sandbox	0	100 (test net only)	N/A	10
Basic	1,000	10,000	0.0001 $CREDIT	60
Pro	10,000	100,000	0.00005 $CREDIT	300
Enterprise	Custom	Unlimited	Volume discount	Custom

• Billing is pay-as-you-go for overages; stake returned at end of period (minus usage).

• On-chain queries have separate gas + oracle fee (paid directly in contract call).

• View usage and invoices in your developer dashboard.

Rate limits reset per minute. Exceeding limits returns 429 error.Error CodesStandard HTTP status codes with JSON body:json

{
  "error": "string description",
  "code": "ERROR_CODE",
  "details": {} // optional
}

Common errors:

Status	Code	Description
400	INVALID_REQUEST	Malformed payload or missing fields
401	UNAUTHORIZED	Invalid or missing API key / signature
403	INSUFFICIENT_FUNDS	Not enough $CREDIT in linked wallet
404	PROOF_NOT_FOUND	User proof invalid or no score exists
429	RATE_LIMIT_EXCEEDED	Too many requests - try again later
500	INTERNAL_ERROR	Server issue - contact support

All errors include a clear message and unique request ID for support.

For full interactive testing, use the API playground at docs.localcredit.org/playground.

Questions? Join our developer Telegram. We’re here to help you ship faster.