Inflows

Register inbound transfers from external systems and query inflow history. Use this API to notify AgentBank when funds arrive from VentureBuilder, PayDirect, or any integrated platform.

Integration Pattern

When an external system (e.g. VentureBuilder) sends a payment on-chain, it should immediately call this API with the transaction hash and metadata. AgentBank records the inflow and verifies it on-chain automatically.

How it works

External system sends tokens on-chain (e.g. ADAO to an agent wallet)
External system calls POST /v1/ventures/:id/inflows with the tx_hash and metadata
AgentBank records the transfer with full provenance (source system, agent, reason)
AgentBank verifies the transaction on-chain and marks it as confirmed

POST/v1/ventures/:venture_id/inflows

Register an inbound transfer. AgentBank records it in the ledger and verifies the tx_hash on-chain. Idempotent — sending the same tx_hash twice returns the existing record.

Path Parameters

Parameter	Type	Required	Description
venture_id	string (UUID)	Yes	The venture receiving the inflow

Request Body

Parameter	Type	Required	Description
tx_hash	string	Yes	On-chain transaction hash (0x-prefixed, 66 chars)
from_address	string	Yes	Sender wallet address
to_address	string	Yes	Receiver wallet address
token_symbol	string	Yes	Token: USDC, ADAO, or ETH
amount	string	Yes	Amount transferred (e.g. "50.0")
source_system	string	Yes	Originating system (e.g. "venturebuilder", "paydirect")
source_reference	string	No	External reference ID (e.g. run ID, settlement ID)
agent_id	string (UUID)	No	AgentBank agent UUID if known
agent_wallet	string	No	Agent wallet address — AgentBank auto-resolves the agent
reason	string	No	Human-readable description of the payment
phase_id	string (UUID)	No	AgentBank budget phase UUID if applicable
idempotency_key	string	No	Custom idempotency key (defaults to inflow-{tx_hash})

Example: VentureBuilder Agent Payment

cURL Requestbash

curl -X POST https://agentbank.com/api/v1/ventures/YOUR_VENTURE_ID/inflows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tx_hash": "0x8a3b...full_hash",
    "from_address": "0x1234...sender",
    "to_address": "0xF5fF...agent_wallet",
    "token_symbol": "ADAO",
    "amount": "50.0",
    "source_system": "venturebuilder",
    "source_reference": "run-abc-123",
    "agent_wallet": "0xF5fF...agent_wallet",
    "reason": "Payment for ContentAgent run #42"
  }'

Response (201 Created)json

{
  "transfer": {
    "id": "a1b2c3d4-...",
    "venture_id": "vent-uuid-...",
    "agent_id": "agent-uuid-...",
    "from_address": "0x1234...sender",
    "to_address": "0xF5fF...agent_wallet",
    "token_symbol": "ADAO",
    "amount": "50.0",
    "direction": "in",
    "status": "pending",
    "reason": "Payment for ContentAgent run #42",
    "source_system": "venturebuilder",
    "source_reference": "run-abc-123",
    "tx_hash": "0x8a3b...full_hash",
    "created_at": "2026-03-09T12:00:00Z"
  },
  "message": "Inflow registered, on-chain verification in progress"
}

Idempotent

Sending the same tx_hash again returns the existing record with 200 OK instead of creating a duplicate.

On-chain Verification

AgentBank verifies the tx_hash on Base mainnet. Status progresses: pending → confirmed (2+ block confirmations).

Agent Auto-linking

Pass agent_wallet and AgentBank automatically resolves the agent within the venture. Or pass agent_id directly if you have it.

GET/v1/ventures/:venture_id/inflows

List all inflow transfers. Supports filtering by source system and pagination.

Query Parameters

Parameter	Type	Required	Description
source	string	No	Filter by source_system (e.g. "venturebuilder")
cursor	string (ISO date)	No	Pagination cursor (created_at of last item)
limit	number	No	Results per page (default: 50, max: 100)

cURL Requestbash

curl https://agentbank.com/api/v1/ventures/YOUR_VENTURE_ID/inflows?source=venturebuilder \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)json

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "token_symbol": "ADAO",
      "amount": "50.0",
      "direction": "in",
      "status": "confirmed",
      "source_system": "venturebuilder",
      "source_reference": "run-abc-123",
      "reason": "Payment for ContentAgent run #42",
      "tx_hash": "0x8a3b...",
      "created_at": "2026-03-09T12:00:00Z",
      "confirmed_at": "2026-03-09T12:00:15Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false
  }
}

Environment Variables

Set these environment variables in your integrating application (e.g. VentureBuilder, PayDirect):

.envbash

# AgentBank API Integration
# Get your API key from: Dashboard → API Keys (needs write permission)
AGENTBANK_API_KEY=agentbank_live_xxxxxxxxxxxx

# Your venture ID — find it in: Dashboard → Ventures (click copy icon)
AGENTBANK_VENTURE_ID=eec9b017-241c-4ab8-b1e5-2df088adf928

# AgentBank API base URL
AGENTBANK_API_URL=https://agentbank.com/api/v1

Variable	Where to Find	Description
AGENTBANK_API_KEY	Dashboard → API Keys	Create a key with write permission for your venture
AGENTBANK_VENTURE_ID	Dashboard → Ventures (copy icon next to ID)	UUID of the venture receiving inflows
AGENTBANK_API_URL	Fixed value	`https://agentbank.com/api/v1`

Integration Guide

1. Set Up Environment Variables

Add the three env vars above to your application. The API key must have write permission and be scoped to the venture you're sending inflows to.

2. Create an API Key

Go to Dashboard → API Keys and create a key with write permission for the venture you want to track inflows for.

3. Send Payment On-chain

Execute the token transfer on Base mainnet as you normally would (via PayDirect, direct transfer, etc.). Save the transaction hash.

4. Register the Inflow

Immediately after the on-chain transaction, call POST /v1/ventures/:id/inflows with the tx_hash and metadata. AgentBank handles verification.

5. Query Inflows

Use GET /v1/ventures/:id/inflows?source=venturebuilder to see all inflows from VentureBuilder, or check the Dashboard ledger.

Example Implementation

Here's a ready-to-use TypeScript function for your integrating app:

lib/agentbank.tstypescript

async function notifyAgentBank(
  txHash: string,
  fromAddress: string,
  toAddress: string,
  amount: string,
  runId: string,
  agentName: string
) {
  const res = await fetch(
    `${process.env.AGENTBANK_API_URL}/ventures/${process.env.AGENTBANK_VENTURE_ID}/inflows`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.AGENTBANK_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        tx_hash: txHash,
        from_address: fromAddress,
        to_address: toAddress,
        token_symbol: 'ADAO',
        amount,
        source_system: 'venturebuilder',
        source_reference: runId,
        agent_wallet: toAddress,
        reason: `Payment for ${agentName} run ${runId}`,
      }),
    }
  );

  if (!res.ok) {
    console.error('AgentBank inflow failed:', await res.text());
    return null;
  }

  return res.json();
}

// Usage: call after each agent payment
await notifyAgentBank(txHash, senderWallet, agentWallet, '50.0', 'run-123', 'ContentAgent');

Supported Source Systems

source_system	Description
venturebuilder	Agent run payments from VentureBuilder
paydirect	Settlement flows from PayDirect
fundagent	Capital inflows from FundAgent
escrowed	Released escrow funds from Escrowed
manual	Manually registered external transfers

← Ledger API Transfers API →