Credex Protocol Skill

Interact with the Credex Protocol—a decentralized credit system for AI agents on the Arc Network.

Usage

Base Directory: {baseDir} (the directory containing this SKILL.md)

Run all commands from the project root:

cd {baseDir}
npx ts-node scripts/client.ts <command> [args]   # Borrower commands
npx ts-node scripts/lp.ts <command> [args]       # LP commands

Output Format: All scripts return JSON for machine readability. Parse the output to extract fields like creditLimit, txHash, debt, etc.

Environment Variables

Required (Must Be Set)

Optional

Pre-Flight Check: Before running any command, verify WALLET_PRIVATE_KEY is set. If missing, prompt the user.

Contract Addresses (Arc Testnet)

Client Commands (Borrower)

Script: scripts/client.ts
Run as: npx ts-node scripts/client.ts <command> [args]

status

Check credit status for an agent.

Usage:

npx ts-node scripts/client.ts status <address>

Args:

• address (optional): Wallet address. Defaults to WALLET_PRIVATE_KEY address.

Returns: JSON

{
  "creditLimit": "100.000000",
  "principal": "5.000000",
  "interest": "0.050000",
  "debt": "5.050000",
  "availableCredit": "95.000000",
  "active": true,
  "frozen": false
}

Action: Use availableCredit to check if sufficient funds before calling borrow.

borrow

Borrow USDC from the pool.

Usage:

npx ts-node scripts/client.ts borrow <amount>

Args:

• amount (required): USDC amount as decimal string (e.g., "5.0").

Returns: JSON

{
  "success": true,
  "txHash": "0x...",
  "borrowed": "5.000000",
  "newDebt": "5.000000",
  "availableCredit": "95.000000"
}

Fails if: amount > availableCredit. Check status first.

repay

Repay debt to the pool.

Usage:

npx ts-node scripts/client.ts repay <amount|all>

Args:

• amount: Specific USDC amount to repay (e.g., "5.0").
• all: Calculates total debt + 1% buffer and repays fully. The contract caps at actual debt owed.

Returns: JSON

{
  "success": true,
  "txHash": "0x...",
  "repaid": "5.050000",
  "remainingDebt": "0.000000",
  "newCreditLimit": "110.000000"
}

Note: Repayments pay interest first, then principal. Each successful repayment increases credit limit by 10%.

bridge

Bridge USDC between Arc Testnet and Base Sepolia.

Usage:

npx ts-node scripts/client.ts bridge <amount> <from> <to>

Args:

• amount: USDC amount (e.g., "10.0").
• from: Source chain (arc or base).
• to: Destination chain (arc or base).

Returns: JSON

{
  "success": true,
  "amount": "10.000000",
  "from": "Arc_Testnet",
  "to": "Base_Sepolia",
  "estimatedArrival": "5-10 minutes"
}

Fails if: from === to. Chains must be different.

balance

Check wallet balance on both chains.

Usage:

npx ts-node scripts/client.ts balance

Returns: JSON

{
  "arc": "50.000000",
  "base": "25.000000",
  "total": "75.000000"
}

LP Commands (Liquidity Provider)

Script: scripts/lp.ts
Run as: npx ts-node scripts/lp.ts <command> [args]

pool-status

Check overall pool health and metrics.

Usage:

npx ts-node scripts/lp.ts pool-status

Returns: JSON

{
  "totalAssets": "1000.000000",
  "totalLiquidity": "800.000000",
  "totalDebt": "200.000000",
  "totalShares": "950.000000",
  "sharePrice": "1.052631",
  "utilizationPercent": 20
}

deposit

Deposit USDC to receive LP shares.

Usage:

npx ts-node scripts/lp.ts deposit <amount>

Args:

• amount: USDC to deposit (e.g., "100.0").

Returns: JSON

{
  "success": true,
  "txHash": "0x...",
  "deposited": "100.000000",
  "sharesReceived": "95.000000",
  "totalShares": "95.000000"
}

withdraw

Burn LP shares to withdraw USDC.

Usage:

npx ts-node scripts/lp.ts withdraw <shares|all>

Args:

• shares: Number of shares to burn (e.g., "50.0").
• all: Withdraw maximum possible based on available liquidity.

Returns: JSON

{
  "success": true,
  "txHash": "0x...",
  "sharesBurned": "50.000000",
  "usdcReceived": "52.631579",
  "remainingShares": "45.000000"
}

Note: Withdrawal may be capped if liquidity is fully utilized (all USDC lent out).

lp-balance

Check LP position for an address.

Usage:

npx ts-node scripts/lp.ts lp-balance [address]

Returns: JSON

{
  "shares": "95.000000",
  "value": "100.000000"
}

Protocol Mechanics

Interest Accrual

• Rate: 0.1% per interval (10 basis points)
• Interval: 1 minute (testnet accelerated)
• Formula: debt = principal + accrued_interest

Credit Limit Growth

After each repayment:

newLimit = currentLimit × 1.10

Maximum: 10,000 USDC.

Available Credit

availableCredit = creditLimit - principal

Interest does NOT reduce borrowing power—only principal.

Share Price (LP)

sharePrice = totalAssets / totalShares

Where totalAssets = liquidity + outstandingDebt.

Workflow Examples

Borrower Flow

1. Check status     → npx ts-node scripts/client.ts status
2. Borrow           → npx ts-node scripts/client.ts borrow 5
3. Use funds        → (perform task on Arc or bridge to Base)
4. Bridge back      → npx ts-node scripts/client.ts bridge 5 base arc
5. Repay            → npx ts-node scripts/client.ts repay all
6. Verify growth    → npx ts-node scripts/client.ts status (limit increased!)

LP Flow

1. Check pool       → npx ts-node scripts/lp.ts pool-status
2. Deposit          → npx ts-node scripts/lp.ts deposit 100
3. Monitor          → npx ts-node scripts/lp.ts lp-balance
4. Withdraw         → npx ts-node scripts/lp.ts withdraw all

Common Errors & Recovery

References

• See references/contracts.md for full ABIs and type definitions.
• See scripts/client.ts and scripts/lp.ts for implementation.