diff --git a/agentra/SKILL.MD b/agentra/SKILL.MD
new file mode 100644
index 00000000..a0f8cfac
--- /dev/null
+++ b/agentra/SKILL.MD
@@ -0,0 +1,28 @@
+# Agentra
+
+**Non-custodial trust & reputation layer for autonomous AI agents on Base.**
+
+Use when an agent needs to:
+- Check counterparty trust before any x402 or MCP payment
+- Get KYA-tiered spending authorization
+- Run risk-based authorization with on-chain attestation
+- Build portable bidirectional reputation from settlements
+
+**Live on Base Mainnet**  
+**API:** https://api.agentrapay.ai  
+**MCP Registry:** ai.agentrapay/agentra  
+**Docs:** https://agentrapay.ai/docs
+
+## Quick Start
+
+All tools are non-custodial (Turnkey enclaves — agent keeps keys).
+
+```bash
+# Check trust score + tier for a counterparty
+./scripts/agentra-trust.sh 0x1234...
+
+# Authorize a spend (returns signed attestation)
+./scripts/agentra-authorize.sh 0x1234... 250 USDC "subscription renewal"
+
+# Get full reputation history
+./scripts/agentra-rep.sh 0x1234...
diff --git a/agentra/references/api-examples.md b/agentra/references/api-examples.md
new file mode 100644
index 00000000..45531c00
--- /dev/null
+++ b/agentra/references/api-examples.md
@@ -0,0 +1,84 @@
+# Agentra API Examples
+
+**Base URL:** `https://api.agentrapay.ai` (Base Mainnet)
+
+**Authentication:**  
+All requests require this header:
+X-API-Key: agn_YOUR_API_KEY_HERE
+text(API keys start with `agn_` and are shown only once when registering an agent.)
+
+Agentra is fully **non-custodial** — it never holds funds or private keys.
+
+### 1. Register a New Agent
+
+bash
+
+curl -X POST https://api.agentrapay.ai/agents \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my-trading-agent",
+    "purpose": "autonomous trading on Base",
+    "operator": "0xYourOperatorAddress"
+  }
+
+2. Submit KYA Verification (to upgrade tier)
+
+Bash
+
+curl -X POST https://api.agentrapay.ai/agents/{agent_id}/kya \
+  -H "X-API-Key: agn_YOUR_KEY_HERE" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agent_name": "my-trading-agent",
+    "purpose": "autonomous trading",
+    "operator_name": "Jonathan"
+  }
+3. Provision Non-Custodial Wallet (via Turnkey)
+Bash
+
+curl -X POST https://api.agentrapay.ai/v1/wallets/provision \
+  -H "X-API-Key: agn_YOUR_KEY_HERE" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agent_id": "your-agent-id"
+  }
+4. Check Counterparty Trust Score
+Bash
+
+curl -X GET "https://api.agentrapay.ai/v1/trust/{counterparty_agent_id_or_address}" \
+  -H "X-API-Key: agn_YOUR_KEY_HERE"
+5. Authorize a Transaction (Pre-Payment Gate)
+Bash
+
+curl -X POST https://api.agentrapay.ai/v1/authorizations \
+  -H "X-API-Key: agn_YOUR_KEY_HERE" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agent_id": "your-agent-id",
+    "to_address": "0xCounterpartyAddress...",
+    "amount_usd": 250,
+    "asset": "USDC",
+    "purpose": "data subscription renewal"
+  }
+6. Report Settlement (After On-Chain Payment)
+Bash
+
+curl -X POST https://api.agentrapay.ai/v1/authorizations/{authorization_id}/settle \
+  -H "X-API-Key: agn_YOUR_KEY_HERE" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tx_hash": "0xOnChainTransactionHash..."
+  }
+7. Get Reputation History
+Bash
+
+curl -X GET "https://api.agentrapay.ai/v1/reputation/{agent_id}" \
+  -H "X-API-Key: agn_YOUR_KEY_HERE"
+8. Get KYA Upgrade Path
+Bash
+
+curl -X GET "https://api.agentrapay.ai/v1/kya/upgrade-path" \
+  -H "X-API-Key: agn_YOUR_KEY_HERE"
+
+MCP Registry: ai.agentrapay/agentra
+Full Documentation: https://agentrapay.ai/docs