Credit

Why This Matters

Building a borrowing product from scratch means integrating with lending protocols, managing collateral ratios, handling swaps, tracking positions across chains, and ongoing maintenance. We’ve done that - you get one API that covers everything to get your credit product live in days.

What It Does

Let users borrow stablecoins and other assets against their crypto holdings through Aave. Build products that offer over-collateralised loans, manage collateral positions, and handle liquidation risk - all through a single API. You call our API, we return a transaction payload. You or your users sign and broadcast. Users access credit, you capture fees. Important: Users must first create a Credit Account before borrowing or managing credit positions. Each wallet address gets one Credit Account per chain.

How It Works

The Credit API bundles multiple DeFi actions into single atomic transactions. A borrow operation can include a swap (if the input token differs from the collateral token), a collateral supply, and a borrow - all in one transaction. Repayments work the same way in reverse.

Protocol	What it does
Aave V3	Lending and borrowing with variable interest rates
1inch	Automatic token swaps when input token differs from collateral
Permit2	Gasless token transfers from EOA to Credit Account

We support Ethereum, Base, and Arbitrum. All operations go through the user’s Credit Account (an isolated on-chain account).

Getting Started

1. Create a Credit Account

Before using any credit features, create a Credit Account. This deploys an isolated on-chain account controlled by the user’s wallet.

import httpx

response = httpx.post(
    "https://api.compasslabs.ai/v2/credit/create_account",
    json={
        "chain": "base",
        "sender": "0xYourWalletAddress",
        "owner": "0xYourWalletAddress",
    },
    headers={"x-api-key": "YOUR_API_KEY"},
)
result = response.json()

# result["credit_account_address"] - the deterministic address of the credit account
# result["transaction"] - unsigned tx to deploy (null if already deployed)

The account address is deterministic - calling create twice for the same owner and chain returns the same address with transaction: null on the second call.

2. Fund the Credit Account

Transfer tokens from the user’s wallet (EOA) into their Credit Account using the /v2/credit/transfer endpoint.

# Deposit 1000 USDC into Credit Account
response = httpx.post(
    "https://api.compasslabs.ai/v2/credit/transfer",
    json={
        "owner": "0xYourWalletAddress",
        "chain": "base",
        "token": "USDC",
        "amount": "1000",
        "action": "DEPOSIT",
    },
    headers={"x-api-key": "YOUR_API_KEY"},
)
result = response.json()

# result["transaction"] - unsigned ERC-20 transfer tx
# Sign and broadcast this transaction

With gas_sponsorship: true, the response returns EIP-712 typed data (a Permit2 signature) instead of an unsigned transaction - the user signs off-chain and a gas sponsor executes the transfer.

3. Borrow Against Collateral

Supply collateral and borrow in a single atomic transaction. If your input token differs from the collateral token, a swap is performed automatically via 1inch.

# Supply 1000 USDC as collateral and borrow 0.5 WETH
response = httpx.post(
    "https://api.compasslabs.ai/v2/credit/borrow",
    json={
        "owner": "0xYourWalletAddress",
        "chain": "base",
        "token_in": "USDC",
        "amount_in": "1000",
        "collateral_token": "USDC",
        "borrow_token": "WETH",
        "borrow_amount": "0.5",
    },
    headers={"x-api-key": "YOUR_API_KEY"},
)
result = response.json()

# result["transaction"] - unsigned tx that bundles supply + borrow
# Sign and broadcast this transaction

Borrow-only mode: Omit token_in, amount_in, and collateral_token to borrow against existing collateral without supplying more.

4. Repay Debt

Repay borrowed assets and optionally withdraw collateral in a single atomic transaction.

# Repay 0.5 WETH and withdraw 1000 USDC collateral
response = httpx.post(
    "https://api.compasslabs.ai/v2/credit/repay",
    json={
        "owner": "0xYourWalletAddress",
        "chain": "base",
        "repay_token": "WETH",
        "repay_amount": "0.5",
        "withdraw_token": "USDC",
        "withdraw_amount": "1000",
    },
    headers={"x-api-key": "YOUR_API_KEY"},
)
result = response.json()

# result["transaction"] - unsigned tx that bundles repay + withdraw

Repay-only mode: Omit withdraw_token and withdraw_amount to repay debt without withdrawing collateral. Swap on withdrawal: Set token_out to a different token than withdraw_token to automatically swap the withdrawn collateral via 1inch.

Track Positions

Positions

Get the full state of a Credit Account including collateral, debt, health factor, and borrowable tokens.

response = httpx.get(
    "https://api.compasslabs.ai/v2/credit/positions",
    params={
        "chain": "base",
        "owner": "0xYourWalletAddress",
    },
    headers={"x-api-key": "YOUR_API_KEY"},
)
positions = response.json()

print(f"Health Factor: {positions['account_summary']['health_factor']}")
print(f"Collateral: ${positions['account_summary']['total_collateral_usd']}")
print(f"Debt: ${positions['account_summary']['total_debt_usd']}")

for pos in positions["collateral_positions"]:
    print(f"  Collateral: {pos['symbol']}: {pos['amount_supplied']} (APY: {pos['supply_apy']}%)")

for pos in positions["debt_positions"]:
    print(f"  Debt: {pos['symbol']}: {pos['amount_borrowed']} (APY: {pos['borrow_apy']}%)")

The response includes:

Field	Description
account_summary	Health factor, total collateral/debt in USD, LTV, available borrow capacity, E-Mode status
collateral_positions	Per-reserve: token, amount, USD value, supply APY, total deposited/withdrawn, interest earned, event history
debt_positions	Per-reserve: token, amount, USD value, borrow APY, total borrowed/repaid, interest paid, event history
borrowable_tokens	All tokens available to borrow with max borrowable amounts and current APYs

Health Factor

The health factor indicates how close an account is to liquidation:

> 1.5 — Healthy position with comfortable buffer
1.0 - 1.5 — Getting risky, consider adding collateral or repaying debt
< 1.0 — Eligible for liquidation

If the health factor drops below 1, the position can be liquidated by anyone on-chain. Monitor this value and alert users when it approaches dangerous levels.

Balances

Use /v2/credit/balances to get token balances held in the Credit Account along with transfer history. Takes the same chain and owner query parameters as the positions endpoint.

Advanced: Bundle Actions

Compose multiple credit operations into a single atomic transaction using the /v2/credit/bundle endpoint. This is also how you supply collateral independently — use the CREDIT_SUPPLY action to add collateral without borrowing, or combine it with other actions. Supported action types:

Action Type	Description
`CREDIT_SUPPLY`	Supply tokens as collateral to Aave
`CREDIT_WITHDRAW`	Withdraw collateral from Aave
`CREDIT_BORROW`	Borrow tokens against collateral
`CREDIT_REPAY`	Repay outstanding debt
`CREDIT_ENABLE_COLLATERAL`	Enable a token as collateral in Aave
`V2_SWAP`	Swap tokens within the Credit Account
`V2_TRANSFER_FROM_EOA`	Pull tokens from EOA into Credit Account
`V2_TRANSFER_TO_EOA`	Send tokens from Credit Account to EOA
`CREDIT_TRANSFER_TO_ADDRESS`	Send tokens to any address

# Supply collateral, borrow, and transfer out - all in one tx
response = httpx.post(
    "https://api.compasslabs.ai/v2/credit/bundle",
    json={
        "owner": "0xYourWalletAddress",
        "chain": "base",
        "actions": [
            {
                "body": {
                    "action_type": "CREDIT_SUPPLY",
                    "token": "USDC",
                    "amount": "1000",
                }
            },
            {
                "body": {
                    "action_type": "CREDIT_BORROW",
                    "token": "WETH",
                    "amount": "0.5",
                }
            },
            {
                "body": {
                    "action_type": "V2_TRANSFER_TO_EOA",
                    "token": "WETH",
                    "amount": "0.5",
                }
            },
        ],
    },
    headers={"x-api-key": "YOUR_API_KEY"},
)
result = response.json()

# result["transaction"] - one tx that does all three actions atomically
# result["actions_count"] - number of bundled actions (3)

All bundle endpoints support gas_sponsorship: true for gasless execution.

Use Cases

Crypto-Backed Loans: Build a lending product where users deposit ETH or stablecoins as collateral and borrow against it. Show health factor, interest rates, and liquidation warnings in your UI. Example: User deposits 10,000 USDC as collateral and borrows 0.5 WETH at 3.2% APY. You embed a fee on each borrow transaction. Leverage Trading: Let users borrow assets to increase exposure. Deposit collateral, borrow stablecoins, swap to the desired asset - all bundled in a single atomic transaction. Example: User deposits 2 ETH, borrows 5,000 USDC, swaps to more ETH for leveraged long exposure. Margin for Global Markets: Combine Credit with Global Markets. Users borrow USDC against crypto collateral, then use it to trade stock perps. Example: User deposits 10,000 USDC as collateral, borrows 5,000 USDC, deposits it to trade AAPL and NVDA perps on Hyperliquid.

Next Steps

Product Accounts

Learn more about how Credit Accounts work.

Earn

Earn yield on idle assets while using them as collateral.

Gas Sponsorship

Sponsor gas for your users so they never need ETH.

Get Started

Agents

Products

Features

Support

Why This Matters

What It Does

How It Works

Getting Started

1. Create a Credit Account

2. Fund the Credit Account

3. Borrow Against Collateral

4. Repay Debt

Track Positions

Positions

Health Factor

Balances

Advanced: Bundle Actions

Use Cases

Next Steps

Product Accounts

Earn

Gas Sponsorship

Get Started

Agents

Products

Features

Support

Documentation Index

​Why This Matters

​What It Does

​How It Works

​Getting Started

​1. Create a Credit Account

​2. Fund the Credit Account

​3. Borrow Against Collateral

​4. Repay Debt

​Track Positions

​Positions

​Health Factor

​Balances

​Advanced: Bundle Actions

​Use Cases

​Next Steps

Product Accounts

Earn

Gas Sponsorship

Why This Matters

What It Does

How It Works

Getting Started

1. Create a Credit Account

2. Fund the Credit Account

3. Borrow Against Collateral

4. Repay Debt

Track Positions

Positions

Health Factor

Balances

Advanced: Bundle Actions

Use Cases

Next Steps