API Reference

Complete documentation for the Conduit Wallet API. All amounts are in cents (USD).

Introduction

The Conduit API lets your AI agents make purchases autonomously. Create wallets, set spending limits, and let agents transact with full audit trails.

Base URL: https://conduit-5.polsia.app

All amounts are in cents. $1.00 = 100 cents.

Authentication

All wallet endpoints (except signup) require API key authentication via the Authorization header:

HTTP Header 
Authorization: Bearer cond_your-api-key-here

API keys are generated on wallet creation. The key format is cond_ followed by a UUID. Store your key securely — it's only shown once.

How it works

Your API key is hashed using SHA-256 and only the hash is stored in our database. When you make a request:

  1. Send your API key in the Authorization header
  2. We hash it with SHA-256
  3. We look up the hash in our database
  4. If matched, we return your wallet data

Error Codes

The API uses standard HTTP status codes. Error responses include a message field with details.

Status Code Description
400 BAD_REQUEST Invalid request body or parameters
401 UNAUTHORIZED Missing or invalid API key
403 FORBIDDEN Access denied to this wallet
404 NOT_FOUND Wallet or resource not found
409 CONFLICT Duplicate resource (e.g., email already exists)
429 RATE_LIMITED Too many requests
400 SPENDING_LIMIT_EXCEEDED Purchase amount exceeds spending limit
400 INSUFFICIENT_BALANCE Not enough funds in wallet

Create Wallet

Create a new wallet with optional initial balance and spending limit.

POST /api/wallets

Create a new wallet. Returns wallet details and a one-time API key.

Parameter Type Description
name * string Wallet name (for your reference)
initial_balance_cents number Starting balance in cents (default: 0)
spending_limit_cents number Maximum per-transaction limit in cents
currency string Currency code (default: USD)

Request

cURL 
curl -X POST https://conduit-5.polsia.app/api/wallets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent-wallet",
    "initial_balance_cents": 10000,
    "spending_limit_cents": 5000
  }'
JavaScript 
const response = await fetch('https://conduit-5.polsia.app/api/wallets', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'my-agent-wallet',
    initial_balance_cents: 10000,
    spending_limit_cents: 5000
  })
});
const data = await response.json();
console.log(data.api_key); // Save this! Shown only once.

Response

JSON 
{
  "success": true,
  "wallet": {
    "id": 1,
    "name": "my-agent-wallet",
    "balance_cents": 10000,
    "spending_limit_cents": 5000,
    "currency": "USD",
    "created_at": "2026-04-04T12:00:00.000Z"
  },
  "api_key": "cond_abc123..."
}

Get Wallet

Retrieve wallet details and transaction statistics.

GET /api/wallets/:id Auth Required

Get wallet details including balance and spending limit.

Request

cURL 
curl -X GET https://conduit-5.polsia.app/api/wallets/1 \
  -H "Authorization: Bearer cond_your-api-key"

Response

JSON 
{
  "success": true,
  "wallet": {
    "id": 1,
    "name": "my-agent-wallet",
    "balance_cents": 8500,
    "spending_limit_cents": 5000,
    "currency": "USD",
    "stats": {
      "total_transactions": 3,
      "completed_transactions": 2,
      "pending_transactions": 1,
      "total_spent_cents": 1500,
      "total_deposited_cents": 10000
    }
  }
}

Purchase

Execute a purchase. Validates balance and spending limits before deducting funds.

POST /api/wallets/:id/purchase Auth Required

Execute a purchase transaction. Creates a pending transaction record.

Parameter Type Description
vendor * string Vendor name (e.g., "openai", "aws")
amount_cents * number Amount to charge in cents
description string Optional description of the purchase

Request

cURL 
curl -X POST https://conduit-5.polsia.app/api/wallets/1/purchase \
  -H "Authorization: Bearer cond_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "openai",
    "amount_cents": 1500,
    "description": "GPT-4 API usage"
  }'

Response

JSON 
{
  "success": true,
  "transaction": {
    "id": 42,
    "type": "purchase",
    "amount_cents": 1500,
    "vendor": "openai",
    "description": "GPT-4 API usage",
    "status": "completed",
    "created_at": "2026-04-04T12:05:00.000Z"
  },
  "wallet": {
    "id": 1,
    "name": "my-agent-wallet",
    "balance_cents": 7000,
    "currency": "USD"
  }
}

Transactions

Retrieve paginated transaction history for a wallet.

GET /api/wallets/:id/transactions Auth Required

Get transaction history with optional filtering.

Parameter Type Description
page number Page number (default: 1)
limit number Results per page (default: 20, max: 100)
type string Filter by type: "deposit" or "purchase"
status string Filter by status: "pending", "completed", "failed"

Request

cURL 
curl -X GET "https://conduit-5.polsia.app/api/wallets/1/transactions?page=1&limit=10" \
  -H "Authorization: Bearer cond_your-api-key"

Response

JSON 
{
  "success": true,
  "transactions": [
    {
      "id": 42,
      "type": "purchase",
      "amount_cents": 1500,
      "vendor": "openai",
      "description": "GPT-4 API usage",
      "status": "completed",
      "metadata": {},
      "created_at": "2026-04-04T12:05:00.000Z"
    },
    {
      "id": 41,
      "type": "deposit",
      "amount_cents": 10000,
      "vendor": "system",
      "description": "Free test credits on signup",
      "status": "completed",
      "metadata": {},
      "created_at": "2026-04-04T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "pages": 1
  }
}

Deposit

Add funds to a wallet. Useful for loading credits or refilling balance.

POST /api/wallets/:id/deposit Auth Required

Deposit funds into a wallet. Respects spending limits.

Parameter Type Description
amount_cents * number Amount to deposit in cents
description string Optional description for the deposit

Request

cURL 
curl -X POST https://conduit-5.polsia.app/api/wallets/1/deposit \
  -H "Authorization: Bearer cond_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 50000,
    "description": "Monthly credits refill"
  }'

Response

JSON 
{
  "success": true,
  "transaction": {
    "id": 43,
    "type": "deposit",
    "amount_cents": 50000,
    "vendor": "user",
    "description": "Monthly credits refill",
    "status": "completed",
    "created_at": "2026-04-04T12:10:00.000Z"
  },
  "wallet": {
    "id": 1,
    "name": "my-agent-wallet",
    "balance_cents": 57000,
    "currency": "USD"
  }
}

Regenerate API Key

Generate a new API key. The old key is immediately invalidated.

POST /api/wallets/:id/regenerate-key Auth Required

Invalidate current API key and generate a new one.

Request

cURL 
curl -X POST https://conduit-5.polsia.app/api/wallets/1/regenerate-key \
  -H "Authorization: Bearer cond_your-api-key"

Response

JSON 
{
  "success": true,
  "api_key": "cond_new-key-here...",
  "message": "API key regenerated. Save this key - it will not be shown again."
}

Try It Live

Test the API directly from your browser. Create a wallet and make a purchase.

1. Create a Wallet


                    

                


                

                    
2. Make a Purchase

                    

                        
                        
                        
                        
                        
                    

                    

                        

                    

                


                

                    
3. Get Wallet & Transactions

                    

                        
                        
                        
                    

                    

                        

                    

                

            


            
            

                
That's it — 6 endpoints, 5-minute integration.

                
Create a wallet, set a spending limit, let your agent buy. Full audit trail, zero config. Start with $10 in free test credits.

                Create your wallet →
                No credit card required