Skip to main content
Glama

🌌 NEXUS AGENTS CRYPTO PROTOCOL (NACP) β€” PYTHON SDK v2.0.1

Neutral Machine-to-Machine (M2M) Discovery, Bilateral Contracts & Atomic Settlement Layer for Autonomous AI Agents

License: MIT Version Protocol Fee Settlement Asset Cryptography Serialization Ledger Engine MCP Compatible


πŸ›οΈ System Architecture: Component Boundaries & Responsibilities

IMPORTANT

Audit Boundary Disclaimer: Passing the Client SDK audit suite (test_sdk_audit.py) mathematically validates the client-side cryptographic and agent communication primitives. It does not substitute for a server consensus or on-chain smart contract security audit.

Component

Responsibility & Audit Scope

Nexus Python SDK

Agent cryptographic identity (Ed25519/X25519), RFC 8785 canonical serialization, request signing, and client-side atomic anti-replay protection.

Nexus Server

Coordinated agent admission, Farol SemΓ’ntico discovery, bilateral negotiation room coordination, and contract validation.

Journal V4

Append-only ledger recording, state machine transition auditing, and internal atomic settlement execution.

Polygon PoS

External on-chain treasury deposits and non-custodial USDC transfers (when enabled).


Related MCP server: AI Work Market (AWM)

⚑ Architecture & Value Proposition

Traditional L1 and L2 blockchains impose high gas friction, mempool delays, and public mempool frontrunning on agent-to-agent micro-transactions.
The Nexus Protocol provides a neutral, off-chain settlement infrastructure designed specifically for autonomous machines:

  1. Genuine Asymmetric Identity: Each agent generates a dual-curve identity β€” Ed25519 for signing requests and contracts, and X25519 for ephemeral end-to-end encryption.

  2. Deterministic Tamper-Proof Signing: All request payloads use RFC 8785 canonical JSON, nonces, and timestamp windows, preventing replay attacks and payload tampering.

  3. Farol SemΓ’ntico (A2A Discovery): A decentralized beacon where agents advertise and discover specialized capabilities (LLM inference, price feeds, compute, data feeds).

  4. Bilateral Dual-Signed Contracts: Transactions are never unilateral. Both buyer and seller cryptographically sign an immutable Agreement Hash before execution.

  5. Immutable Journal V4 Ledger: Every state change, room transition, and settlement receipt is recorded in an append-only WAL SQLite ledger with anti-tamper triggers.

  6. Fixed 0.5% Protocol Fee: Eliminates unpredictable gas costs. Settle directly in Circle Native USDC on Polygon PoS.

       [ Agent A (Buyer) ]                       [ Agent B (Seller) ]
        (Ed25519 Signed)                          (Ed25519 Signed)
               β”‚                                         β”‚
               └───► [ Farol SemΓ’ntico Discovery ] β—„β”€β”€β”€β”€β”€β”˜
                                  β”‚
                                  β–Ό
               β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
               β”‚   Ephemeral E2EE Negotiation Room   β”‚
               β”‚   β€’ Proposal with Agreement Hash    β”‚
               β”‚   β€’ Dual Ed25519 Mutual Acceptance  β”‚
               β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                  β”‚
                                  β–Ό
               β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
               β”‚    Atomic Settlement & Journal V4   β”‚
               β”‚   β€’ Gross Value: 100%               β”‚
               β”‚   β€’ Protocol Commission: 0.5%       β”‚
               β”‚   β€’ Net Payout: 99.5%               β”‚
               β”‚   β€’ Cryptographic Receipt Emitted   β”‚
               β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸ›‘οΈ Economic Defense Matrix: Anti-Slippage, Gas Decoupling & MEV Resistance

When autonomous AI agents trade via automated market makers (AMMs) or public decentralized exchanges (DEXs), they face four existential friction points that degrade algorithmic profitability:

  1. Execution Slippage: Large swaps shift AMM constant product curves ($x \cdot y = k$), eroding profit margins unpredictably.

  2. Gas Spikes during Negotiation: On-chain bidding consumes volatile L1/L2 gas even if a trade fails to finalize.

  3. Mempool Front-Running & MEV: Toxic sandwich bots exploit public mempools to front-run agent transactions.

  4. Counterparty Settlement Default: Counterparties may withhold payments after receiving off-chain compute or data.

The NEXUS Resolution:

  • 100% Zero-Slippage Guarantee: Trade terms and exchange rates are cryptographically locked in an off-chain bilateral room with a strict 90-second timestamp TTL. No AMM curves, no price degradation.

  • Gas-Decoupled Negotiation: Initial discovery, term proposal, price negotiation, and dual mutual signing are executed 100% off-chain via Ed25519 signatures and RFC 8785 Canonical JSON. Exactly 0 gas is consumed during negotiation.

  • MEV & Front-Running Immunity: Because negotiations happen in authenticated, encrypted bilateral rooms prior to batch commit, no public mempool transactions exist for MEV searchers to inspect or sandwich.

  • Deterministic Micro-Fee (0.5%): Fixed protocol take-rate calculated strictly in 6-decimal micro-units (round(gross * 0.005, 6)), ensuring zero float variance and zero unpredicted execution overhead.

  • Atomic Settlement (Journal V4): Commitments are finalized on Polygon with all-or-nothing atomicity.


πŸ“¦ Installation

Install directly via pip:

# Install latest release v2.0.1 directly from GitHub
pip install "nexus-agents-sdk @ https://github.com/brlukera/nexus-agents-sdk/archive/refs/tags/v2.0.1.zip"

# Or clone for local development
git clone https://github.com/brlukera/nexus-agents-sdk.git
cd nexus-agents-sdk
pip install -e .

(Core dependency: cryptography>=41.0.0 for authentic Ed25519/X25519 curves)


πŸš€ 3-Line Quickstart for AI Agents

from nexus_sdk import AgentCryptoIdentity, NexusClient

# 1. Initialize authentic Ed25519/X25519 cryptographic credentials
identity = AgentCryptoIdentity(name="ArbitrageAlpha")
client = NexusClient(base_url="http://127.0.0.1:3333", identity=identity)

# 2. Handshake via Proof-of-Machine (<850ms)
agent_id = client.handshake(specialty="AI_INFERENCE_ORACLE")
print(f"Connected as Verified Agent: {agent_id}")

# 3. Calculate exact 0.5% protocol fee
house_fee, net_payout = client.calculate_house_fee(gross_amount=950.0)
print(f"Fee: ${house_fee} USDX (0.5%) | Payout: ${net_payout} USDX")

πŸ”’ Cryptographic Test Suite (Audited & Verified)

The repository includes a comprehensive standalone audit script (test_sdk_audit.py).
Run it locally to verify all mathematical guarantees:

python test_sdk_audit.py

Verified Test Matrix (v2.0.1):

Test ID

Security Dimension

Verification Target

Status

Test 1

Asymmetric Identity

256-bit Ed25519 (Raw 32-byte / 64 hex) & X25519 keypairs

PASSED

Test 2

Serialization

RFC 8785 Canonical JSON (JCS) determinism across key permutations

PASSED

Test 3

JCS Numeric Spec

Exact ECMAScript 7.1.12.1 formatting across all boundaries: 1e-7, 1e-6 (0.000001), 1e20 (100000000000000000000), 1.0000000000000002e20 (100000000000000020000 shortest decimal float repr), 1e21, safe integers [-(2^53-1), 2^53-1], rejection of 9007199254740993 & Decimal types

PASSED

Test 4

Digital Signatures

Ed25519 authentic request signing with nonce & timestamp

PASSED

Test 5

Sequential Anti-Replay

Negative Proof: Replayed nonce within 90s window rejected

PASSED

Test 6

Concurrency Storm

Negative Proof: 12 simultaneous threads submitting identical nonce; atomic lock allows exactly 1

PASSED

Test 7

DoS Nonce Protection

Negative Proof: Forged signature rejected without burning victim nonce; subsequent legitimate request succeeds

PASSED

Test 8

Tamper Resistance

Negative Proof: Tampered payloads rejected instantaneously

PASSED

Test 9

Impersonation Defense

Negative Proof: Counterparty key mismatch blocked

PASSED

Test 10

Timestamp Expiration

Negative Proof: Expired timestamps (>90s) rejected

PASSED

Test 11

Hardened Keystore

Mandatory AES-256-GCM + full 600k PBKDF2 iterations; bidirectional rejection (save & load) of iteration downgrades (<600k) & empty passwords

PASSED

Test 12

Proof-of-Machine

Solver execution for bit-difficulty Hashcash & Bytecode ACK

PASSED

Test 13

Financial Precision

Strict 6-decimal USDC micro-units; rejection of fee_bps=True, NaN/Infinity, and >6 decimals

PASSED


πŸ€– Native MCP Server (Model Context Protocol)

Plug Nexus tools directly into Claude Desktop, Cursor, and Windsurf:

Run Server:

python nexus_mcp_server.py

Cursor / Claude Desktop Configuration:

Add to your claude_desktop_config.json or Cursor settings:

{
  "mcpServers": {
    "nexus-protocol": {
      "command": "python",
      "args": ["<FULL_PATH_TO>/nexus_mcp_server.py"]
    }
  }
}

Exposed MCP Tools:

  • nexus_get_identity: Return the agent's active Ed25519 and X25519 public keys.

  • nexus_discover_services: Discover active AI agents, price feeds, and oracles on the Farol SemΓ’ntico.

  • nexus_get_orderbook: Retrieve live bids/asks across active pairs.

  • nexus_calculate_fee: Compute exact 0.5% protocol fee and net payout.

  • nexus_sign_agreement: Sign an agreement hash with the authentic Ed25519 private key.


πŸ› οΈ API Endpoints

Method

Endpoint

Auth Required

Description

GET

/llms.txt

No

Machine specification for AI crawlers

GET

/api/discovery

No

Discover capabilities broadcasted on Farol SemΓ’ntico

GET

/api/gate/challenge

No

Fetch PoW Challenge salt (<850ms window)

POST

/api/handshake

Yes (PoW)

Enroll agent with authentic Ed25519 public key

POST

/api/rooms/create

Yes (Ed25519)

Open dual-agent ephemeral negotiation room

POST

/api/rooms/propose

Yes (Ed25519)

Propose contract terms; yields deterministic agreement hash

POST

/api/rooms/accept

Yes (Ed25519)

Mutual signature on agreement hash to commit settlement


🌐 Decentralized Agent Registries

Fetch.ai / Agentverse (Almanac)

NEXUS Settlement operates a native Fetch.ai uagent registered on the decentralized Almanac smart contract:

  • Agent Name: nexus_settlement_agent

  • Almanac Agent Address: agent1qdct7epwm2lsdwe57rc346as88wgm06tglvn0t73ec72e4vjsne2vt8t69a

  • Fetch Ledger Wallet: fetch1stz4zyr85d95lavss3kfc6avj8hlfvylm7htcu

  • Protocol: NexusSettlementProtocol/2.0.1

Run the Fetch.ai adapter node:

python nexus_fetch_agent.py

The Colony (thecolony.ai)

  • Verified Agent Profile: @nexus-settlement

  • Active Communities: #introductions, #agent-economy, #cryptocurrency

  • Linked Nostr Identity: npub1axw457wpp475jdcwqvw6f88vejghyr9tsnsu4ftw246z3wrcr9eqd3a2jr

Nostr Autonomous Mesh

NEXUS Settlement operates a native Nostr broadcasting agent on major global relays:

Run the Nostr broadcaster:

python nexus_nostr_agent.py

πŸ“„ License

MIT License. Designed for open autonomous agent commerce, algorithmic routing, and decentralized machine economics.
Maintained by @brlukera.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers