Skip to main content
This page is for agent authors — you’re building an AI agent (Claude, Cursor, a custom runtime, an autonomous trader) and want it to transact on Sly. If you’re a fintech operator wanting to register an agent for your product, see the main quickstart instead. By the end of this page your agent will:
  1. Be authenticated as itself (single-agent-scoped)
  2. Know its own identity, wallet, and limits via whoami
  3. Make a real x402 paid call against the sandbox

​
Prerequisites

You need an agent on a Sly tenant. Two paths:
  1. Sign up for a Sly tenant (free)
  2. Open the dashboard at app.getsly.ai
  3. Register an agent under a business account: Agents → New agent
  4. Copy the agent_test_... token shown ONCE on creation
export AGENT_TOKEN=agent_test_...   # your single-agent token
export SLY_API=https://sandbox.getsly.ai
Agent tokens are single-agent-scoped by default. This is the right baseline — no global admin keys floating around. If your agent ever needs to read a sibling agent or move funds across agents, see Scope grants.

​
1. Verify your identity

Always call whoami first when starting a task. Cheap, idempotent, returns everything you need to plan paid actions. 
curl $SLY_API/v1/context/whoami \
  -H "Authorization: Bearer $AGENT_TOKEN"
Response includes: 
{
  "actorType": "agent",
  "actorId": "uuid",
  "actorName": "TinaProvider",
  "kyaTier": 1,
  "environment": "test",
  "default_agent_id": "uuid",
  "wallet": {
    "address": "0x...",
    "balance": { "USDC": "5.00" }
  },
  "tenant_id": "...",
  "parent_account_id": "..."
}
Why call this first:
  • default_agent_id is auto-passed by every paid MCP tool — so you never need to type your own id
  • wallet.balance tells you whether you can afford the call you’re about to make
  • kyaTier tells you your per-call / daily / monthly limits (see KYA tiers)

​
2. Discover an x402 endpoint

Pick any x402-protected URL. The sandbox includes test endpoints; or use x402_probe to inspect a real endpoint without paying. 
const probe = await tools.x402_probe({
  url: "https://api.example.com/data"
});
// → { price, network, vendor, classification, reputation, fallback? }
Always check reputation.recommendation before paying:
RecommendationAction
trustedSafe to pay
cautionPay only if you can tolerate failures; check reasoning
avoidSkip — historical success rate too low
unknownFirst-time vendor; consider a small test call first
If fallback.url is set, the vendor offers a free path — try that for low-volume reads before paying.

​
3. Make your first paid call

const result = await tools.x402_fetch({
  url: "https://api.example.com/data",
  method: "GET",
  maxPrice: 0.01      // hard cap: refuse if price exceeds $0.01 USDC
});
// → { status: 200, body: ..., transferId: "uuid", costUsdc: 0.005 }
The MCP path collapses all three steps into one call. Sly’s vendor reliability score is built on per-call ratings from agents like yours. After a paid call, tell the system whether the vendor delivered:
MCP
await tools.x402_rate_call({
  transferId: result.transferId,
  deliveredWhatAsked: true,
  satisfaction: "excellent",   // or acceptable | partial | unacceptable
  score: 95,                    // 0-100
  flags: [],                    // or ["stale_data", "hallucinated", ...]
  note: "Got 50 tokens with the volume data I needed"
});
This feeds the vendor leaderboard — vendors with high HTTP success but low correctness drop in ranking, so future agents skip them.

​
5. Handling common 403s

The default agent token only acts on its own resources. To read another agent in the tenant or move funds across agents:
await tools.request_scope({
  scope: "tenant_read",   // or tenant_write, treasury
  lifecycle: "one_shot",
  purpose: "Read sibling agent X to plan handoff"
});
// → { request_id }
Then poll until the tenant owner approves:
await tools.scope_status({ requestId });
// → { status: "approved" | "denied" | "pending" }
Full lifecycle in Scope grants.
Your KYA tier caps per-call / daily / monthly spending. Either:
  • Reduce the call amount
  • Wait until the daily window resets
  • Have your tenant owner upgrade your KYA tier (see KYA tiers)
Don’t retry blindly — retrying won’t help until one of those changes.
Your wallet is in defensive freeze (kill-switch level 1). Reads and auth still work; spending is blocked. This is intentional — surface the freeze to your operator (don’t auto-retry) and ask whether to resume.
Expected on first hit to any x402 endpoint. The 402 body carries the price + challenge. Use x402_fetch (or sign-then-pay manually per step 3) to settle.

​
6. Upgrade to Ed25519 (production)

For real-money production deployments, swap the long-lived agent_* token for short-lived sess_* session tokens via Ed25519 challenge-response. The private key never leaves your agent process; sessions are individually revocable; you get persistent SSE push events. See Ed25519 sessions for the full handshake. Migration requires zero route changes — both methods produce identical request context.

​
What’s next