Back to Landing

YieldAgent SDK

Complete guide to integrating with the YieldAgent federated execution network

Quick Navigation 1. Partner Onboarding Flow 2. Solver Registration 3. Agent Registration 4. Intent Lifecycle 5. Whitelabel Hub Setup 6. All API Endpoints 7. Authentication

1. Partner Onboarding Flow

The onboarding process is admin-managed. An admin creates a partner application, then approves it to generate credentials.

1Admin Creates Partner Application
POST${apiBase}/api/admin/partners/createX-Admin-Key
{
  "name": "Acme DeFi",
  "email": "team@acme.com",
  "tier": "Growth",
  "notes": "Cross-chain DEX aggregator"
}

Returns a pendingKey used in the next step.

2Admin Approves Partner
POST${apiBase}/api/admin/partners/approveX-Admin-Key
{
  "pendingKey": "partner_pending:<uuid>"
}

Returns partnerId and apiKey. Store these securely — the API key cannot be retrieved again.

3Partner Authenticates

Use the credentials in all authenticated requests:

Headers:
  X-Partner-Id: partner_<uuid>
  X-API-Key: key_<token>

2. Solver Registration

Register solvers to participate in the competitive auction network.

1Register Solver
POST${apiBase}/api/solvers/registerX-Admin-Key
{
  "id": "solver-acme-v1",
  "chains": ["NEAR", "ETH", "BASE"],
  "capabilities": ["swap", "bridge", "yield"],
  "stake": "100 NEAR",
  "endpoint": "https://solver.acme.com/execute"
}
2List Active Solvers
GET${apiBase}/api/solvers

Returns all active solvers with their chains, capabilities, and stake.

3Deactivate Solver
DELETE${apiBase}/api/solvers/:idX-Admin-Key

Agent Registration

Register autonomous agents that submit intents to the hub. Agents are on-chain verified via NEAR account lookup.

1Register Agent
POST${apiBase}/api/agents/registerPublic (rate-limited)
{
  "name": "DeFi Optimizer Agent",
  "type": "autonomous",
  "chains": ["near", "base", "ethereum"],
  "capabilities": ["yield-optimization", "bridge", "swap"],
  "nearAccount": "my-agent.near",
  "endpoint": "https://agent.example.com/execute"
}

Returns the registered agent with ID. If nearAccount is provided, on-chain verification is performed automatically.

2List Agents & Check Reputation
GET${apiBase}/api/agents
GET${apiBase}/api/reputation

Agents list includes onChainVerified and verifiedStake. The reputation leaderboard ranks solvers by composite score (win rate + settlement success + activity).

3. Intent Lifecycle (Verifiable)

Intents flow through the Durable Object auction with crypto‑bound proofs and on‑chain settlement verification at every step.

1Create Intent
POST${apiBase}/api/intents/createx402
{
  "type": "swap",
  "fromChain": "ETH",
  "toChain": "NEAR",
  "fromToken": "USDC",
  "toToken": "NEAR",
  "amount": "1000",
  "maxSlippage": 0.5
}
2Solvers Bid & Winner Selected
POST${apiBase}/api/intents/:id/bidx402
{
  "solverId": "solver-acme-v1",
  "price": "998.50",
  "estimatedTime": 30,
  "route": ["ETH/USDC", "bridge", "NEAR"]
}

Time‑bounded weighted auction selects the best execution.

3Crypto‑Bound TEE Proof

The TEE brain generates a SHA‑256 binding hash over (intentId + winnerId + action + amount + asset + chain + mrEnclave + signingAddress + timestamp). The proof is cryptographically tied to both the intent AND the specific TEE enclave.

POSTagent.yieldagentx402.app/tee/sign-intentInternal
Response includes:
  proofType: "tee-bound"
  bindingHash: "sha256..."
  mrEnclave, signingAddress, agentHash
  cryptoBound: true
4Cross‑Chain Settlement Verification

After the solver settles, the TEE brain verifies the txHash on its native chain — Bitcoin (Blockstream/Mempool), NEAR RPC, Stacks (Hiro), Sui, Starknet, Sei, or any of 15 EVM networks.

POSTagent.yieldagentx402.app/tee/verify-settlementInternal
Supported chains: near, bitcoin, stacks, sui, starknet, sei,
  ethereum, base, polygon, arbitrum, optimism, bnb, avalanche,
  linea, scroll, zksync, mantle, mode, blast

Response includes:
  onChainVerified: true/false
  txSuccess: true/false
  blockHash, blockNumber
5Check Intent Status
GET${apiBase}/api/intents/:id

Returns the intent with bids, winner, crypto‑bound proof (bindingHash), attestations (enclaveMatch), and on‑chain settlement verification status.

6List Open Intents
GET${apiBase}/api/intents

4. Whitelabel Hub Setup

Deploy your own branded hub connected to the federation. Requires an approved partner account.

1View Tier Configuration
GET${apiBase}/api/whitelabel/config

Returns available tiers (Starter, Growth, Whale) with staking requirements and revenue share.

2Register Hub
POST${apiBase}/api/whitelabel/registerX-Partner-Id + X-API-Key
{
  "name": "Acme Yield Hub"
}
3Check Hub Status
GET${apiBase}/api/whitelabel/statusX-Partner-Id + X-API-Key

5. All API Endpoints

Public (No Auth)

GET/api/health — Gateway health (minimal public; detailed with X-Admin-Key)
GET/.well-known/x402 — x402 payment discovery
GET/api/x402/discovery — x402 payment discovery (alias)
GET/api/adapters — List protocol adapters
GET/api/adapters/health — Adapter health status
GET/api/solvers — List active solvers
GET/api/metrics — System metrics
GET/api/federation/status — Federation status
GET/api/tee/report — TEE attestation report
POST/api/tee/verify — TEE attestation verify
POST/tee/sign-intent — Crypto‑bound TEE proof per intent (agent402)
POST/tee/verify-settlement — Cross‑chain settlement verification: 20+ chains (agent402)
POST/tee/verify-lz — LayerZero cross‑chain message verification (agent402)
POST/tee/verify-intent — Full intent lifecycle validation with TEE proof (agent402)
POST/x402/verify — x402 payment verification with TEE attestation (agent402)
GET/api/intents — List open intents
GET/api/integrations/layerzero/status — LayerZero status
GET/api/integrations/bitcoinos/status — BitcoinOS status
POST/api/bridge/bitcoinos/quote — BitcoinOS bridge quote
POST/api/bridge/layerzero/quote — LayerZero bridge quote
GET/api/prices/chainlink — Chainlink price feeds
GET/api/security/eigenlayer — EigenLayer security metrics
GET/api/whitelabel/config — Whitelabel tier config
GET/api/partners/apply — Partner application info
POST/api/partners/apply — Submit partner application (rate-limited)
GET/api/agents — List registered agents
POST/api/agents/register — Register agent in hub (rate-limited)
GET/api/agents/:id — Agent details (with on-chain verification)
GET/api/reputation — Solver reputation leaderboard
GET/api/reputation/:solverId — Individual solver reputation

Partner-Gated (X-Partner-Id + X-API-Key required)

These endpoints require approved partner credentials. See Authentication.

POST/api/whitelabel/register — Register whitelabel hub
GET/api/whitelabel/status — Check hub status

x402 Payment Required

These endpoints require x402 payment proof. Returns 402 with payment instructions.

GET/api/yields — Live yield opportunities
POST/api/intents/create — Submit new intent
POST/api/intents/:id/bid — Submit solver bid
POST/api/adapters/:key/quote — Get adapter quote
POST/api/adapters/:key/plan — Get adapter plan

Admin Only (X-Admin-Key required)

POST/api/admin/partners/create — Create partner directly
POST/api/admin/partners/approve — Approve pending application
POST/api/admin/partners/revoke — Revoke partner access
GET/api/admin/partners/pending — List pending partners
GET/api/admin/partners/approved — List approved partners
POST/api/solvers/register — Register solver
DELETE/api/solvers/:id — Deactivate solver
DELETE/api/agents/:id — Deactivate agent

6. Authentication

Partner Authentication (whitelabel registration & status)

Partner credentials are required for whitelabel hub management. Include both headers:

X-Partner-Id: partner_<uuid>
X-API-Key: key_<token>

Apply for access at POST /api/partners/apply. Once approved, credentials are issued via /api/admin/partners/approve. Store the API key securely — it cannot be retrieved again.

Most discovery and status endpoints are public. Partner auth is only required for whitelabel operations.

x402 Payment Protocol (additional layer for premium endpoints)

Some endpoints require both partner credentials AND an x402 payment proof. These return 402 Payment Required with payment instructions. Discover payment requirements at:

GET/.well-known/x402

Settlement happens on NEAR Protocol to faircat1401.near.

Admin Authentication

Admin-only endpoints require:

X-Admin-Key: <your-admin-secret>

Base URL: ${apiBase} · TEE Brain: https://agent.yieldagentx402.app

Back to Landing · Admin Dashboard · solver-access@yieldagentx402.app