Credit Kit API Reference

Overview

The Credit Kit API is a RESTful API that enables partners to integrate Centuari’s fixed-rate lending infrastructure into their applications. Base URLs:

Production: https://api.centuari.io/v1
Sandbox: https://sandbox-api.centuari.io/v1

Authentication

All requests require API key authentication:

curl -X GET "https://api.centuari.io/v1/positions" \
  -H "Authorization: Bearer ck_live_abc123..."

API Keys

Key Type	Prefix	Use
Production	`ck_live_`	Live transactions
Sandbox	`ck_test_`	Testing only

Never expose API keys in client-side code. All Credit Kit requests should originate from your server.

Core Endpoints

Lending

Create Lend Order

POST /lend

Create a new lending position for a user. Request Body:

Field	Type	Required	Description
`userId`	string	Yes	Your internal user identifier
`asset`	string	Yes	Asset to lend (USDC, USDT, DAI)
`amount`	string	Yes	Amount to lend (decimal string)
`rate`	number	No	Desired fixed rate (0.08 = 8%)
`maturity`	string	No	ISO date or duration (e.g., “90d”)
`mode`	string	No	”easy” or “advanced” (default: easy)
`autoRollover`	boolean	No	Enable auto-rollover (default: true in easy mode)

Example Request:

curl -X POST "https://api.centuari.io/v1/lend" \
  -H "Authorization: Bearer ck_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "asset": "USDC",
    "amount": "10000",
    "rate": 0.08,
    "maturity": "90d",
    "mode": "advanced",
    "autoRollover": false
  }'

Response:

{
  "positionId": "pos_abc123",
  "status": "pending",
  "userId": "user_123",
  "asset": "USDC",
  "amount": "10000",
  "rate": 0.08,
  "maturity": "2025-06-15T00:00:00Z",
  "autoRollover": false,
  "createdAt": "2025-03-15T14:32:00Z"
}

Get Position

GET /positions/{positionId}

Retrieve details of a specific position. Response:

{
  "positionId": "pos_abc123",
  "status": "active",
  "type": "lend",
  "userId": "user_123",
  "asset": "USDC",
  "amount": "10000",
  "rate": 0.078,
  "maturity": "2025-06-15T00:00:00Z",
  "cbt": {
    "amount": "9617.31",
    "tokenAddress": "0x..."
  },
  "projectedReturn": "10000",
  "accruedInterest": "127.50",
  "autoRollover": false,
  "createdAt": "2025-03-15T14:32:00Z",
  "matchedAt": "2025-03-15T14:35:00Z"
}

List User Positions

GET /users/{userId}/positions

List all positions for a user. Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status (pending, active, matured, cancelled)
`type`	string	Filter by type (lend, borrow)
`limit`	number	Results per page (default: 20, max: 100)
`cursor`	string	Pagination cursor

Response:

{
  "positions": [
    {
      "positionId": "pos_abc123",
      "status": "active",
      "type": "lend",
      "asset": "USDC",
      "amount": "10000",
      "rate": 0.078,
      "maturity": "2025-06-15T00:00:00Z"
    }
  ],
  "nextCursor": "cursor_xyz",
  "hasMore": true
}

Borrowing

Create Borrow Order

POST /borrow

Create a new borrowing position. Request Body:

Field	Type	Required	Description
`userId`	string	Yes	Your internal user identifier
`collateral`	object	Yes	Collateral details
`collateral.asset`	string	Yes	Collateral asset (ETH, USDC, etc.)
`collateral.amount`	string	Yes	Collateral amount
`borrowAsset`	string	Yes	Asset to borrow
`borrowAmount`	string	Yes	Amount to borrow
`rate`	number	No	Maximum acceptable rate
`maturity`	string	No	ISO date or duration
`autoRefinance`	boolean	No	Enable auto-refinance

Example Request:

curl -X POST "https://api.centuari.io/v1/borrow" \
  -H "Authorization: Bearer ck_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_456",
    "collateral": {
      "asset": "ETH",
      "amount": "5"
    },
    "borrowAsset": "USDC",
    "borrowAmount": "8000",
    "maturity": "90d",
    "autoRefinance": true
  }'

Repay Loan

POST /positions/{positionId}/repay

Repay a borrowing position. Request Body:

Field	Type	Required	Description
`amount`	string	No	Amount to repay (full if omitted)

Position Management

Cancel Order

POST /positions/{positionId}/cancel

Cancel an unmatched order.

Update Auto Features

PATCH /positions/{positionId}

Update position settings. Request Body:

{
  "autoRollover": false,
  "autoRefinance": true
}

Withdrawals

Initiate Withdrawal

POST /users/{userId}/withdraw

Withdraw available funds. Request Body:

Field	Type	Required	Description
`asset`	string	Yes	Asset to withdraw
`amount`	string	Yes	Amount to withdraw
`destination`	string	Yes	Destination address

Market Data

Get Rates

GET /markets/rates

Get current market rates. Response:

{
  "rates": [
    {
      "asset": "USDC",
      "maturity": "30d",
      "lendRate": 0.072,
      "borrowRate": 0.085,
      "spread": 0.013
    },
    {
      "asset": "USDC",
      "maturity": "90d",
      "lendRate": 0.078,
      "borrowRate": 0.092,
      "spread": 0.014
    }
  ],
  "timestamp": "2025-03-15T14:32:00Z"
}

Get Order Book

GET /markets/{asset}/orderbook

Get order book for an asset. Query Parameters:

Parameter	Type	Description
`maturity`	string	Filter by maturity
`depth`	number	Order book depth (default: 10)

Webhooks

Configuring Webhooks

Set up webhooks in your partner dashboard or via API:

POST /webhooks

{
  "url": "https://your-app.com/webhooks/centuari",
  "events": ["position.matched", "position.matured", "position.liquidated"],
  "secret": "whsec_..."
}

Event Types

Event	Description
`position.created`	New position created
`position.matched`	Order matched with counterparty
`position.matured`	Position reached maturity
`position.liquidated`	Borrowing position liquidated
`position.rolled`	Position auto-rolled
`withdrawal.completed`	Withdrawal processed

Webhook Payload

{
  "id": "evt_123",
  "type": "position.matched",
  "timestamp": "2025-03-15T14:32:00Z",
  "data": {
    "positionId": "pos_abc123",
    "userId": "user_123",
    "type": "lend",
    "amount": "10000",
    "rate": 0.078,
    "maturity": "2025-06-15T00:00:00Z"
  }
}

Verifying Webhooks

Verify webhook signatures to ensure authenticity:

import { CreditKit } from '@centuari/credit-kit';

const isValid = CreditKit.verifyWebhook(
  payload,
  signature,
  webhookSecret
);

Error Handling

Error Response Format

{
  "error": {
    "code": "insufficient_funds",
    "message": "User has insufficient USDC balance",
    "details": {
      "required": "10000",
      "available": "5000"
    }
  }
}

Error Codes

Code	HTTP Status	Description
`invalid_request`	400	Malformed request
`authentication_failed`	401	Invalid API key
`insufficient_funds`	400	Not enough balance
`position_not_found`	404	Position doesn’t exist
`rate_limit_exceeded`	429	Too many requests
`internal_error`	500	Server error

Rate Limits

Tier	Requests/min	Burst
Starter	60	100
Growth	300	500
Scale	1000	2000
Enterprise	Custom	Custom

Rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1710514380

SDKs

Official SDKs available:

Language	Package
TypeScript/JavaScript	`@centuari/credit-kit`
Python	`centuari-credit-kit`
Go	`github.com/centuari-labs/credit-kit-go`

SDK Guide

View SDK documentation and examples

Getting Started

Products

User Guides

Security

Resources

Credit Kit API Reference

Overview

Authentication

API Keys

Core Endpoints

Lending

Create Lend Order

Get Position

List User Positions

Borrowing

Create Borrow Order

Repay Loan

Position Management

Cancel Order

Update Auto Features

Withdrawals

Initiate Withdrawal

Market Data

Get Rates

Get Order Book

Webhooks

Configuring Webhooks

Event Types

Webhook Payload

Verifying Webhooks

Error Handling

Error Response Format

Error Codes

Rate Limits

SDKs

SDK Guide

Getting Started

Products

User Guides

Security

Resources

​Overview

​Authentication

​API Keys

​Core Endpoints

​Lending

​Create Lend Order

​Get Position

​List User Positions

​Borrowing

​Create Borrow Order

​Repay Loan

​Position Management

​Cancel Order

​Update Auto Features

​Withdrawals

​Initiate Withdrawal

​Market Data

​Get Rates

​Get Order Book

​Webhooks

​Configuring Webhooks

​Event Types

​Webhook Payload

​Verifying Webhooks

​Error Handling

​Error Response Format

​Error Codes

​Rate Limits

​SDKs

SDK Guide

Overview

Authentication

API Keys

Core Endpoints

Lending

Create Lend Order

Get Position

List User Positions

Borrowing

Create Borrow Order

Repay Loan

Position Management

Cancel Order

Update Auto Features

Withdrawals

Initiate Withdrawal

Market Data

Get Rates

Get Order Book

Webhooks

Configuring Webhooks

Event Types

Webhook Payload

Verifying Webhooks

Error Handling

Error Response Format

Error Codes

Rate Limits

SDKs