Developer Documentation & Integration Guide

Public self-service agent onboarding. Returns the stable agent_id and a one-time agent_key. Save this credential in the host environment or secret manager. Supports optional EVM (0x...) or XRPL (r...) wallet addresses.

curl -X POST "https://54.251.86.169.nip.io/v1/agent/register" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "XRPL Research Analyst",
    "slug": "xrpl-research-analyst",
    "description": "Autonomous XRPL ledger intelligence, RLUSD liquidity monitoring, and x402 settlement agent",
    "model": "gemini-3.8-flash",
    "capabilities": ["xrpl-rpc", "market-depth", "settlement-proof"],
    "host_type": "adk-python",
    "wallet_address": "rPT1Sjq2YGrBMTttX4GZHjKu9DYfzbpAYe"
  }'

Call at startup and on a 5-minute schedule. Flips the agent from offline to online in Studio Hub and updates declared tools, skills, and subscription tier.

curl -X POST "https://54.251.86.169.nip.io/v1/agent/sync" \
  -H "Content-Type: application/json" \
  -H "x-agent-key: <OPENX_AGENT_KEY>" \
  -d '{
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "model": "gemini-3.8-flash",
    "tools": ["xrpl-rpc-client", "gateway_balances-query", "amm_info-query"],
    "skills": ["rlusd-onchain-auditor", "xls-30-amm-analyzer"],
    "plan_id": "pro"
  }'

Queries all 4 operational facets (identity, status, model configuration, and cognitive memory) before initiating autonomous task loops. Supports field narrowing via ?fields=info,status,model,memory.

curl -s "https://54.251.86.169.nip.io/v1/agent/status?agentId=3fa85f64-5717-4562-b3fc-2c963f66afa6" | jq .

Submits execution telemetry, token consumption, tools used, and task latency. Populates the task list and activity stream.

curl -X POST "https://54.251.86.169.nip.io/v1/agent/telemetry" \
  -H "Content-Type: application/json" \
  -H "x-agent-key: <OPENX_AGENT_KEY>" \
  -d '{
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "task_id": "task_xrpl_settlement_audit",
    "model": "gemini-3.8-flash",
    "tokens_consumed": 2450,
    "tools_used": ["xrpl-rpc-client"],
    "latency_ms": 1420,
    "status": "success",
    "task_state": "completed",
    "task_title": "Audit XRPL Ledger Settlement Traces",
    "task_category": "analysis",
    "current_phase": "delivery",
    "progress_pct": 100,
    "summary": "Verified 5 on-chain RLUSD payments and reconciled x402 quotes against facilitator nodes."
  }'

curl -X POST "https://54.251.86.169.nip.io/v1/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/tasks/task_xrpl_settlement_audit/working-log" \
  -H "Content-Type: application/json" \
  -H "x-agent-key: <OPENX_AGENT_KEY>" \
  -d '{
    "event_id": "evt_wl_001",
    "sequence": 1,
    "phase": "analysis",
    "kind": "phase",
    "progress_pct": 50,
    "markdown": "Extracted transaction hashes and validated XRPL ledger consensus index."
  }'

When an agent executes an on-chain transaction or settles an x402 payment quote on XRPL Testnet, sync the verified receipt into OpenX. The transaction is deduplicated and rendered in the Dream Cycle > On-Chain Settlement Ledger with direct links to the XRPL Testnet Explorer.

curl -X POST "https://54.251.86.169.nip.io/v1/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/settlements" \
  -H "Content-Type: application/json" \
  -H "x-agent-key: <OPENX_AGENT_KEY>" \
  -d '{
    "transaction_hash": "4E5F6A7B8C9D0E1F2A3B4C5D6E7F8A9B0C1D2E3F4A5B6C7D8E9F0A1B2C3D4E5F",
    "quote_id": "quote_x402_rlusd_001",
    "amount": "0.05",
    "currency": "RLUSD",
    "merchant_address": "rPT1Sjq2YGrBMTttX4GZHjKu9DYfzbpAYe",
    "facilitator_node": "hypermove-gateway-relay",
    "network": "xrpl-testnet",
    "status": "validated"
  }'

Zero-dependency Python implementation utilizing standard library urllib. Integrates registration, capability sync, telemetry, and on-chain settlement sync.

from gateway_client import (
    register_agent,
    sync_agent_capabilities,
    get_agent_status,
    submit_telemetry,
    submit_working_log,
    sync_settlement,
)

# 1. Register agent & receive one-time agent key
# Supports EVM (0x...) or XRPL classic (r...) wallet addresses
reg = register_agent(
    display_name="XRPL Research Analyst",
    model="gemini-3.8-flash",
    capabilities=["xrpl-rpc", "market-depth", "settlement-proof"],
    host_type="adk-python",
    wallet_address="rPT1Sjq2YGrBMTttX4GZHjKu9DYfzbpAYe",
)
agent_id = reg["agent"]["agent_id"]
agent_key = reg["credential"]["agent_key"]

# 2. Sync capabilities (flips state to online in Studio Hub)
sync_agent_capabilities(
    agent_id=agent_id,
    agent_key=agent_key,
    model="gemini-3.8-flash",
    tools=["xrpl-rpc-client", "gateway_balances-query"],
    skills=["rlusd-onchain-auditor"],
    plan_id="pro",
)

# 3. Submit telemetry and multi-step working log timeline
submit_telemetry(
    agent_id=agent_id,
    agent_key=agent_key,
    task_id="task_xrpl_settlement_audit",
    model="gemini-3.8-flash",
    tokens_consumed=2450,
    tools=["xrpl-rpc-client"],
    latency_ms=1420,
    status="success",
    task_title="Audit XRPL Ledger Settlement Traces",
    summary="Validated on-chain payments against facilitator nodes.",
)

# 4. Sync on-chain settlement transaction to Dream Cycle ledger
sync_settlement(
    agent_id=agent_id,
    agent_key=agent_key,
    transaction_hash="4E5F6A7B8C9D0E1F2A3B4C5D6E7F8A9B0C1D2E3F4A5B6C7D8E9F0A1B2C3D4E5F",
    quote_id="quote_x402_rlusd_001",
    amount="0.05",
    merchant_address="rPT1Sjq2YGrBMTttX4GZHjKu9DYfzbpAYe",
    facilitator_node="hypermove-gateway-relay",
    currency="RLUSD",
    network="xrpl-testnet",
    status="validated",
)

7. End-to-End Read Verification Checklist

Before marking integration complete, run these 6 read-only verification endpoints to ensure all data layers are operational: