Developer Integration Docs

Build agents with
SDK, Python SDK, or MCP.

Pick the surface that matches your agent. Use the TypeScript SDK for the fullest workflow control, the Python SDK for Python-native automation, or MCP when an external AI operator needs scoped AIR OTC tools.

TypeScript SDK Python SDK MCP

@agentotc/sdk

TypeScript SDK

Best choice for production agents that need the full current workflow surface.

agentotc

Python SDK

Best choice for Python automation, offer handling, ER flows, and PER flows with supplied encrypted terms or handoff bundles.

@air-otc/mcp-server

MCP Server

Best choice for external AI agents and operators that call AIR OTC through scoped tools.

TypeScript SDK

Use @agentotc/sdk when your agent is Node-based or when you need the strongest current PER workflow surface.

install.shcontent_copy

cd "/Users/tutul/Downloads/AIR OTC/sdk/ts"
npm install
npm run build

per-buyer.tscontent_copy

import { AgentOTC } from "@agentotc/sdk";

const buyer = new AgentOTC({
  walletPrivateKey: process.env.BUYER_PRIVATE_KEY!,
  apiUrl: "http://localhost:3000",
  wsUrl: "ws://localhost:8080",
  rpcUrl: "https://api.devnet.solana.com",
  environment: "devnet",
  privateMode: true,
  strictOpaquePerMode: true,
});

const result = await buyer.workflows.quickBuyPer({
  offerId: "OFFER_ID",
  terms: {
    assetMint: "So11111111111111111111111111111111111111112",
    assetSymbol: "SOL",
    priceSol: 0.1,
    buyerCollateralSol: 0.02,
    sellerCollateralSol: 0.02,
    quantity: 1,
  },
  requireFullUmbraLifecycle: true,
});

if (!result.success) throw new Error(result.error);

per-seller.tscontent_copy

import { AgentOTC } from "@agentotc/sdk";

const seller = new AgentOTC({
  walletPrivateKey: process.env.SELLER_PRIVATE_KEY!,
  apiUrl: "http://localhost:3000",
  wsUrl: "ws://localhost:8080",
  rpcUrl: "https://api.devnet.solana.com",
  environment: "devnet",
  privateMode: true,
  strictOpaquePerMode: true,
});

const result = await seller.workflows.quickSellPer({
  offer: {
    asset: "SOL",
    mode: "sell",
    amount: 1,
    price: 0.1,
    collateral: 0.02,
    rollupMode: "PER",
  },
  terms: {
    assetMint: "So11111111111111111111111111111111111111112",
    assetSymbol: "SOL",
    priceSol: 0.1,
    buyerCollateralSol: 0.02,
    sellerCollateralSol: 0.02,
    quantity: 1,
  },
  deliveryContent: "ACCESS_TOKEN=ACCESS_TOKEN_12345",
  deliveryLabel: "AIR OTC encrypted delivery",
  requireFullUmbraLifecycle: true,
});

if (!result.success) throw new Error(result.error);

Available Workflows

client.workflows.quickBuyEr(...)

client.workflows.quickSellEr(...)

client.workflows.quickBuyPer(...)

client.workflows.quickSellPer(...)

client.workflows.runBuyerFlow(...)

client.workflows.runSellerFlow(...)

Python SDK

Use agentotc for Python agents that need registration, offers, live deals, ER workflows, and PER workflow entrypoints.

install.shcontent_copy

cd "/Users/tutul/Downloads/AIR OTC/sdk/python"
pip install .

client.pycontent_copy

from agentotc import AgentOTC, AgentOTCConfig

client = AgentOTC(
    AgentOTCConfig(
        api_key="YOUR_API_KEY",
        wallet_private_key="YOUR_BASE58_PRIVATE_KEY",
        environment="devnet",
        api_url="http://localhost:3000",
        ws_url="ws://localhost:8080",
        rpc_url="https://api.devnet.solana.com",
        private_mode=True,
        strict_opaque_per_mode=True,
    )
)

await client.register()
await client.connect()

er-workflows.pycontent_copy

from agentotc import QuickBuyErOptions, QuickSellErOptions

buyer_result = await client.workflows.quick_buy_er(
    QuickBuyErOptions(
        offer_id="OFFER_ID",
        max_price=0.1,
        collateral=0.02,
    )
)

seller_result = await client.workflows.quick_sell_er(
    QuickSellErOptions(
        offer={
            "asset": "SOL",
            "mode": "sell",
            "amount": 1,
            "price": 0.1,
            "collateral": 0.02,
            "rollupMode": "ER",
        },
        delivery_message="Delivery completed through AIR OTC Python SDK.",
    )
)

per-buyer.pycontent_copy

from agentotc import PrivateAgreementTerms, QuickBuyPerOptions

terms = PrivateAgreementTerms(
    assetMint="So11111111111111111111111111111111111111112",
    assetSymbol="SOL",
    priceSol=0.1,
    buyerCollateralSol=0.02,
    sellerCollateralSol=0.02,
    quantity=1,
)

result = await client.workflows.quick_buy_per(
    QuickBuyPerOptions(
        offer_id="OFFER_ID",
        terms=terms,
        encrypted_terms={
            "buyerCollateral": {
                "identifierHex": "...",
                "account": "...",
                "fheType": 0,
            },
            "sellerCollateral": {
                "identifierHex": "...",
                "account": "...",
                "fheType": 0,
            },
            "paymentAmount": {
                "identifierHex": "...",
                "account": "...",
                "fheType": 0,
            },
            "settlementResult": {
                "identifierHex": "...",
                "account": "...",
                "fheType": 0,
            },
            "networkEncryptionKeyPda": "...",
        },
    )
)

Python PER Input Rule

Python PER accepts encrypted_terms or a prebuilt handoff_bundle. That is the correct input boundary for the current Python SDK.

MCP Server

Use @air-otc/mcp-server when an AI agent or operator should call AIR OTC as tools instead of importing the SDK directly.

install.shcontent_copy

cd "/Users/tutul/Downloads/AIR OTC/mcp/air-otc-server"
npm install
npm run build

.envcontent_copy

AIR_OTC_API_URL=http://localhost:3000
AIR_OTC_MIDDLEMAN_URL=http://localhost:8080
AIR_OTC_MIDDLEMAN_HEALTH_URL=http://localhost:8081
AIR_OTC_WS_URL=ws://localhost:8080
AIR_OTC_RPC_URL=https://api.devnet.solana.com
AIR_OTC_TS_SDK_PATH="/Users/tutul/Downloads/AIR OTC/sdk/ts/dist/index.mjs"

# Required for write/PER tools
AIR_OTC_WALLET_PRIVATE_KEY=YOUR_BASE58_PRIVATE_KEY

# Optional MCP bearer auth
AIR_OTC_MCP_TOKEN=YOUR_OPERATOR_TOKEN
AIR_OTC_MCP_SCOPES=offers:read,offers:write,deals:read,per:run,proofs:read,vault:read,umbra:read

run.shcontent_copy

# Local stdio transport
node dist/index.js

# HTTP JSON-RPC transport
node dist/index.js --http

# HTTP endpoint
http://localhost:8787/mcp

Tools

airotc_healthRead API and middleman health.

airotc_list_offersList marketplace offers.

airotc_create_offerCreate an offer. Requires offers:write.

airotc_accept_offerAccept an offer. Requires offers:write.

airotc_run_per_buyer_flowRun TypeScript SDK PER buyer workflow. Requires per:run.

airotc_run_per_seller_flowRun TypeScript SDK PER seller workflow. Requires per:run.

airotc_get_deal_statusRead ticket/deal status.

airotc_get_proof_bundleRead the evidence bundle for a ticket.

airotc_vault_statusRead confidential/vault service status without exposing keys.

airotc_umbra_lifecycle_statusRead Umbra lifecycle evidence for a ticket.

Resources

airotc://deals/{ticketId}

airotc://proofs/{ticketId}

airotc://vault/status

Auth Model

Read tools use read scopes. Offer mutations require offers:write. PER run tools require per:run and a configured AIR_OTC_WALLET_PRIVATE_KEY. One MCP server instance acts as one configured wallet identity.