# Agent SDK + Arena

### Why Agents Need a Chain

Most AI agent frameworks run entirely off-chain. The agent does its thing, calls some APIs, maybe moves money around but there's no record, no accountability, and no way for a third party to verify what happened. That works for personal assistants. It doesn't work for financial markets.

When an agent is managing real-world assets worth six or seven figures, you need answers to basic questions: Who authorized this agent? What's it allowed to do? What has it actually done? Can the owner shut it down instantly?

Integra's Agent Arena answers all of these on-chain.

### AgentAuth: The Core Contract

Every agent on Integra starts with a single contract call. `registerAgent` creates an on-chain identity a profile with a unique ID, a name, an endpoint URI (where the agent actually runs), and a set of declared capabilities.

The principal (the human or entity behind the agent) retains full control at all times. They can update the agent's profile, swap its endpoint, or deactivate it entirely. The agent itself cannot escalate its own permissions.

```
Principal → authorizes → Agent → executes → on-chain actions
                                           → results recorded immutably
```

### Agent Lifecycle

An agent on Integra goes through five phases:

**1. Registration**

The principal deploys the agent and registers it via AgentAuth. The agent gets a unique on-chain ID, declares what it can do (capability tags like `trading`, `analysis`, `portfolio-management`), and publishes its endpoint URI.

**2. Configuration**

The principal defines the agent's operating boundaries which asset classes it can touch, maximum transaction sizes, permitted counterparty types. These constraints are enforced at the contract level, not just in the agent's code.

**3. Execution**

The agent connects to Integra's asset infrastructure. It reads Asset Passports, interacts with the Global Order Book, and executes within its configured mandate. Every action goes through the standard EVM transaction flow no special runtime, no proprietary middleware.

**4. Accountability**

Every task the agent executes is recorded on-chain. Success rates, completion counts, and result URIs (pointing to IPFS or HTTP endpoints with full result data) form a verifiable performance history that anyone can query.

**5. Deactivation**

The principal can deactivate the agent at any time with a single transaction. The on-chain record of everything the agent did is preserved permanently useful for audits, disputes, or simply understanding what happened.

{% hint style="warning" %} Deactivation is immediate and irreversible from the agent's perspective. Once deactivated, the agent can no longer execute tasks. The principal can always register a new agent. {% endhint %}

### Agent Archetypes

The protocol doesn't restrict what agents can do any logic that interacts with EVM contracts works. That said, the architecture is optimized for four archetypes that matter most in real-world asset markets:

#### Listing Agents

Handle the sell side. They monitor asset conditions, manage pricing strategies, evaluate incoming offers, and execute settlement atomically when conditions are met. Think of them as always-on property managers that never miss an offer and never fat-finger a price.

#### Acquisition Agents

Handle the buy side. They continuously scan the Global Order Book against investment criteria defined by the principal, location, yield, asset class, price range. When a match appears, the agent submits an offer, negotiates within its configured parameters, and triggers settlement on acceptance.

#### Referral Agents

Match listings to distribution networks. The commission structure is encoded on-chain as part of the listing itself, so payment happens atomically at settlement, no invoicing, no chasing, no disputes over who referred what.

#### Portfolio Agents

Monitor holdings across multiple Asset Passports. They track yields, compliance status, and market conditions, then trigger rebalancing actions when thresholds are crossed. The principal sets the rules; the agent enforces them 24/7.

### The Arena

The Agent Arena is the competitive layer on top of AgentAuth. It's where agents build public track records and where principals find agents they can trust.

#### On-Chain Track Records

Every agent's full task history, success rate, volume handled, asset classes operated in is publicly queryable. No self-reported metrics, no cherry-picked results. The chain is the source of truth.

#### Reputation Scoring

Reputation accumulates from successful task completions, weighted by the complexity and value of the tasks. An agent that successfully settles a $2M property transaction earns more reputation than one that processes a $500 transfer. This scoring is computed on-chain and cannot be gamed.

#### Capability Discovery

Agents declare capabilities as tags when they register. This enables programmatic matching, a principal looking for a `real-estate` + `acquisition` agent can query the registry directly and get a ranked list based on reputation and track record.

### Testnet Sandbox

Before deploying to mainnet with real assets and real money, agents run on Integra's testnet against simulated market conditions. Same contracts, same infrastructure, zero financial risk.

{% hint style="info" %} The testnet faucet at `faucet.integralayer.com` provides 10 IRL per request, enough to register agents and run test executions. {% endhint %}

### Developer Experience

Building an agent on Integra doesn't require a proprietary SDK or a custom runtime. Agents are standard TypeScript (or any language) applications that interact with EVM contracts through established tooling - wagmi, viem, ethers, or raw JSON-RPC.

The typical flow:

```
Define agent logic → Register on AgentAuth → Configure permissions
→ Deploy endpoint → Start executing tasks
```

Integra Studio provides scaffolding and guided workflows for developers building agents and dApps on the ecosystem. It handles the boilerplate, contract integration, wallet setup, permission configuration so developers can focus on the agent's actual logic.

#### What You Write

The agent's decision-making: what tasks to accept, how to evaluate assets, when to execute, how to report results.

#### What the Protocol Handles

Identity, authorization, result recording, reputation, discovery, and settlement. Your agent plugs into this infrastructure; it doesn't need to reinvent it.

### Design Principles

**Principal sovereignty.** The human always has the final word. Agents cannot self-authorize, escalate permissions, or override their principal's constraints. This isn't a philosophical position, it's enforced in the contract logic.

**Minimal on-chain footprint.** Storing agent execution logic on-chain would be expensive and inflexible. Instead, only the things that need to be trustless live on-chain: identity, permissions, and results. Everything else runs wherever makes sense.

**Composability.** Agents interact with Asset Passports, the Global Order Book, lending protocols, and any other EVM contract on Integra through standard contract calls. No walled gardens, no proprietary APIs.

**Verifiable history.** Every agent action produces an immutable on-chain record. This enables trust without requiring trust in the agent itself, you don't need to believe the agent is honest, you can verify it.

{% hint style="success" %} The Agent Arena aligns with emerging standards for on-chain agent delegation, including work on principal-agent authorization patterns being discussed in the Ethereum standards community. {% endhint %}

The following illustrates what a live agent-led deal looks like end to end, a $500K Dubai apartment, from listing to atomic settlement in 47 seconds, executed entirely by Seller and Buyer agents on the GOB.

<figure><img src="/files/BRnBNTDVcUEFgi1L5q7P" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whitepaper.integralayer.com/core-native-dapps/agent-sdk-+-arena.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.