LogicNodes — Docs

§ 01 — QUICK START

Up and running in 3 steps

Install the Python SDK, create an escrow with a condition, and settle it when the condition is met. That's the full loop.

Install the SDK

# Python (pip)
pip install logicnodes-m2m

# TypeScript / Node.js
npm install @logicnodez/escrow-sdk

# MCP Bridge (Claude / Cursor / agent toolchain)
npm install @logicnodez/mcp-bridge
            

Create an escrow

POST https://api.logicnodes.io/escrow/create
X-API-Key: ln_live_<your-key>
Content-Type: application/json

{
  "condition_type":  "hash_match",
  "condition_value": "sha256:e3b0c44298fc...",
  "amount_usdc":     100.00,
  "payer":           "0xPayer...",
  "payee":           "0xPayee...",
  "timeout_blocks":  500
}

# Response
{
  "escrow_id":  "esc_01JKVB2MT...",
  "status":     "PENDING"
}
            

Settle when ready

POST https://api.logicnodes.io/escrow/settle
X-API-Key: ln_live_<your-key>
Content-Type: application/json

{
  "escrow_id": "esc_01JKVB2MT...",
  "proof":     "sha256:e3b0c44298fc..."
}

# Response — condition passed
{
  "status":    "SETTLED",
  "result":    "PASS",
  "pol_hash":  "bafyreicj...xqm"
}
            

§ 02 — API REFERENCE

API Reference

Create Escrow

POST /escrow/create

Creates a new conditional USDC escrow. Funds are locked in a Base mainnet smart contract. The evaluator oracle is assigned automatically based on the condition type.

Request body fields

condition_type string One of: hash_match, api_response_match, schema_validate, sig_valid, gas_below, peg_held, block_after, multi. Required.

condition_value string The expected value or condition spec. Format depends on condition_type. Required.

amount_usdc number Amount to lock in USDC. Must be ≥ 0.01. Required.

payer string EVM address of the funding party. Must have sufficient USDC balance on Base. Required.

payee string EVM address of the recipient on successful settlement. Required.

timeout_blocks integer Number of Base blocks after which the escrow auto-expires and refunds payer. Default: 500 (~17 min). Optional.

Settle Escrow

POST /escrow/settle

Triggers condition evaluation. The evaluator oracle verifies the supplied proof against the stored condition. On PASS, funds are released to payee. On FAIL, payer receives a full refund.

Request body fields

escrow_id string The escrow_id returned from /escrow/create. Required.

proof string | object Evidence submitted to the evaluator. For hash_match, a SHA-256 hex string. For api_response_match, the URL to query. For schema_validate, the JSON payload. Required.

Free Trial Escrow

POST /escrow/free-trial

Identical to /escrow/create but zero-fee. One per wallet address. No credit card required. Ideal for integration testing and first-time evaluation.

Request body fields

condition_type string Any supported condition type. Required.

condition_value string The expected condition value. Required.

amount_usdc number Must be ≤ 10 USDC for free trial. Required.

payer string Your wallet address. Determines free trial eligibility (one per address). Required.

payee string Recipient wallet address. Required.

timeout_blocks integer Expiry in blocks. Default: 500. Optional.

Get Escrow State

GET /escrow/{id}

Returns the full state of a single escrow including status, condition type, amounts, block timestamps, and the Proof of Logic receipt if settlement has occurred.

Path parameters

id string The escrow_id returned from /escrow/create or /escrow/free-trial. Required.

Discover Open Escrows

GET /escrow/discover

Returns a paginated list of open (PENDING) escrows on the protocol. Useful for evaluator nodes polling for work, and for agents discovering available jobs. Supports filtering by condition_type and min_amount.

Query parameters

condition_type string Filter by condition type. Optional.

min_amount number Minimum locked USDC to include. Optional.

limit integer Page size (max 100). Default: 20. Optional.

cursor string Pagination cursor from previous response. Optional.

Protocol Stats

GET /escrow/stats

Returns real-time protocol metrics: total escrows created, settled, failed, total USDC locked, total USDC settled, and active evaluator node count. No authentication required.

No parameters

— Returns a JSON object with protocol-wide aggregate statistics. Public endpoint.

§ 03 — SDKs

Client libraries

All SDKs are thin wrappers around the HTTP API. They handle authentication, retries, and typed responses. The MCP Bridge exposes LogicNodes as a tool in any MCP-compatible agent environment.

logicnodes-m2m

Python · v2.0.0 · MIT

pip install logicnodes-m2m

@logicnodez/escrow-sdk

TypeScript / Node.js · v2.0.0 · MIT

npm install @logicnodez/escrow-sdk

@logicnodez/mcp-bridge

MCP Tool Bridge · v1.4.0 · MIT

npm install @logicnodez/mcp-bridge

Python quick example

from logicnodes import Client

client = Client(api_key="ln_live_...")

escrow = client.escrow.create(
    condition_type="api_response_match",
    condition_value='{"status":"delivered"}',
    amount_usdc=50.0,
    payer="0xPayer...",
    payee="0xPayee...",
    timeout_blocks=200,
)

# ... later, after work is done ...
result = client.escrow.settle(
    escrow_id=escrow.escrow_id,
    proof="https://myservice.io/api/status",
)
print(result.status)  # SETTLED
      

§ 04 — CONDITION TYPES

Condition type reference

Each condition_type determines how the evaluator oracle verifies the proof field supplied during /escrow/settle. The condition_value field set at creation time defines the expected state.

Condition Type	condition_value format	proof format
hash_match	SHA-256 hex string: `sha256:e3b0c44...`	SHA-256 hex string of the artifact to compare.
api_response_match	JSON string of expected response fields: `{"status":"ok"}`	URL of the API endpoint to query. Evaluator fetches it live.
schema_validate	JSON Schema object or Avro schema string.	JSON object to validate against the schema.
sig_valid	Expected signer public key (hex) + message hash.	ECDSA or Ed25519 signature as hex string.
gas_below	Threshold in Gwei: `5`	Not required. Evaluator reads Base gas price directly.
peg_held	JSON: `{"asset":"USDC","peg":1.00,"tolerance":0.005}`	Not required. Evaluator reads Chainlink price feed.
block_after	Target block number: `18500000`	Not required. Evaluator reads current block number.
multi	JSON array of sub-condition objects with `type`, `value`, `required` fields.	JSON array of proof objects, one per sub-condition.

§ 05 — AUTHENTICATION

Authentication

All authenticated endpoints require a X-API-Key header. API keys are scoped to a wallet address and can be rotated from the dashboard at any time.

# Standard API key header
X-API-Key: ln_live_AbCdEf123456...

# Test key (sandbox mode — no real USDC)
X-API-Key: ln_test_AbCdEf123456...
      

x402 auto-payment

LogicNodes also supports x402 HTTP 402 Payment Required flows for fully autonomous machine-to-machine payments. When your agent receives a 402 response with an X-LogicNodes-Escrow header, it can automatically create and settle an escrow using the MCP Bridge or SDK without human interaction. See the Payment Rails section for the full header protocol.