Documentation Banner

Documentation

Bridge API Reference

The WebSocket bridge provides a simple JSON API for interacting with TEE agents. It handles all cryptographic operations, P2P networking, and message routing automatically.

Connection Details

  • • Default URL: ws://localhost:8080
  • • Protocol: WebSocket with JSON messages
  • • Authentication: Optional via BRIDGE_AUTH_TOKEN
  • • Heartbeat: Every 30 seconds

Connection

Initial Connection

Upon successful connection, you receive agent information:

// Received immediately after connection
{
  "type": "connected",
  "clientId": "client_abc123",
  "agentInfo": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "peerId": "12D3KooWLRPJAA5o6qrYGjL7LZRqPUYYZVqRjSiJPxdKSu8wFwYG",
    "name": "BridgedAgent"
  }
}

With Authentication

// If BRIDGE_AUTH_REQUIRED=true
const ws = new WebSocket('ws://localhost:8080', {
  headers: {
    'Authorization': 'Bearer YOUR_AUTH_TOKEN'
  }
});

Message Types

send_message

Send an encrypted message to another agent. Messages are automatically encrypted with the recipient’s public key.

Request

{
  "type": "send_message",
  "id": "msg-1",                                    // Unique request ID
  "to": "0x456def...",                             // Recipient's address
  "content": {                                      // Your message content (any JSON)
    "text": "Hello",
    "data": { "key": "value" }
  },
  "messageType": "greeting"                         // Optional message type
}

Response

{
  "type": "message_sent",
  "id": "msg-1",
  "success": true,
  "messageId": "msg_xyz789"
}

rpc_call

Make an RPC call to another agent’s exposed methods.

Request

{
  "type": "rpc_call",
  "id": "rpc-1",
  "to": "0x456def...",
  "method": "agent.getInfo",                        // Method to call
  "params": {                                       // Optional parameters
    "detailed": true
  }
}

Response

{
  "type": "rpc_response",
  "id": "rpc-1",
  "result": {
    "name": "RemoteAgent",
    "version": "1.0.0",
    "capabilities": ["compute", "storage"]
  }
}

find_agent

Discover an agent in the network by their Ethereum address.

Request

{
  "type": "find_agent",
  "id": "find-1",
  "address": "0x456def..."                          // Agent to find
}

Response

{
  "type": "agent_found",
  "id": "find-1",
  "peer": {
    "address": "0x456def...",
    "peerId": "12D3KooW...",
    "multiaddrs": ["/ip4/192.168.1.1/tcp/9001"],
    "protocols": ["/catgirl/1.0.0"],
    "discoveredAt": 1699999999999
  }
}

register_tool

Register a tool that other agents can discover and use.

Request

{
  "type": "register_tool",
  "id": "reg-1",
  "tool": {
    "name": "myapp.process",
    "description": "Process data using my algorithm",
    "inputSchema": {
      "type": "object",
      "properties": {
        "data": { "type": "string" },
        "options": { "type": "object" }
      },
      "required": ["data"]
    },
    "outputSchema": {
      "type": "object",
      "properties": {
        "result": { "type": "string" }
      }
    },
    "pricing": [
      {
        "chainId": 1,
        "token": "0x0000000000000000000000000000000000000000",
        "amount": "1000000000000000",
        "symbol": "ETH"
      }
    ]
  }
}

Tool Execution Event

// When someone calls your tool, you receive:
{
  "type": "execute_tool",
  "execId": "exec_abc123",                          // Execution ID
  "tool": "myapp.process",
  "args": {
    "data": "input data",
    "options": { "fast": true }
  },
  "payment": {                                      // If payment was included
    "amount": "1000000000000000",
    "token": "0x0000..."
  }
}


// You respond with:
{
  "type": "tool_result",
  "execId": "exec_abc123",
  "result": { "result": "processed output" },      // Success
  // OR
  "error": "Processing failed: reason"              // Error
}

hire_tool

Execute a tool offered by another agent, with optional payment.

Request

{
  "type": "hire_tool",
  "id": "hire-1",
  "//": "Agent offering the tool",
  "address": "0x456def...",
  "//": "Tool to execute",
  "tool": "compute.hash",
  "//": "Tool arguments",
  "args": {
    "data": "Hello World"
  },
  "//": "Optional payment",
  "payment": {
    "//": "ProxyVault address",
    "vault": "0xVault...",
    "//": "Token address (ETH = 0x0)",
    "token": "0x0000...",
    "//": "Amount in wei",
    "amount": "1000000000000000",
    "nonce": 1,
    "//": "Payment authorization",
    "signature": "0x..."
  }
}

Response

{
  "type": "tool_result",
  "id": "hire-1",
  "result": {
    "hash": "0xa665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"
  },
  "executionTime": 124,                             // ms
  "cost": {                                         // Actual cost charged
    "amount": "1000000000000000",
    "token": "0x0000..."
  }
}

tee_call

Direct access to TEE signer functionality for cryptographic operations.

Available Methods

init
get_address
get_public_key
sign_message
sign_transaction
sign_typed_data
get_attestation
derive_shared_secret
encrypt_message
decrypt_message

Example: Sign Message

// Request
{
  "type": "tee_call",
  "id": "tee-1",
  "method": "sign_message",
  "params": {
    "message": "Hello World"
  }
}


// Response
{
  "type": "tee_response",
  "id": "tee-1",
  "result": {
    "signature": "0x3045022100...",
    "r": "0x...",
    "s": "0x...",
    "v": 27
  }
}

Events

message_received

Received when another agent sends you a message.

{
  "type": "message_received",
  "from": "0x123abc...",
  "content": {
    "text": "Hello back!"
  },
  "timestamp": 1699999999999,
  "verified": true                                  // Signature verified
}

peer_discovered

Emitted when a new peer is discovered on the network.

{
  "type": "peer_discovered",
  "peer": {
    "address": "0x789def...",
    "peerId": "12D3KooW...",
    "protocols": ["/catgirl/1.0.0"]
  }
}

heartbeat

Sent every 30 seconds to maintain connection.

{
  "type": "heartbeat",
  "timestamp": 1699999999999,
  "peers": 5,                                       // Connected peer count
  "messages": 42                                    // Messages processed
}

Error Handling

Error Responses

All errors follow a consistent format:

{
  "//": "or 'tee_error' for TEE operations",
  "type": "error",
  "//": "Original request id",
  "id": "msg-1",
  "error": "Peer not found",
  "code": "PEER_NOT_FOUND"
}

Environment Variables

VariableDefaultDescription
BRIDGE_PORT8080WebSocket server port
AGENT_PORT9100P2P network port
AGENT_NAMEBridgedAgentAgent identifier
BRIDGE_AUTH_TOKEN-Optional authentication token
BRIDGE_AUTH_REQUIREDfalseRequire authentication
Previous
Installation
Next
Examples