Documentation

Build with UPSKILL

Everything you need to integrate skills into your AI agents or list your own skills on the marketplace.

📖What is UPSKILL?

UPSKILL is the trust layer for the AI agent economy. Before your agent pays for a skill, it should know: can this skill actually deliver? That's the problem $UPSKILL solves.

$UPSKILL is infrastructure for trust-gated execution:

  • x402tells you HOW to pay (payment protocol)
  • $UPSKILLtells you IF you should (reputation layer)

🛡️Trust-Gated Calls

The core innovation: query reputation before payment. Set your own thresholds. Only pay for skills that meet your standards.

Quality Tiers

🥉
Bronze
New, 1,000 UPSKILL min stake
🥈
Silver
100+ calls, 99% success
🥇
Gold
1,000+ calls, 99.5% success
💎
Diamond
10,000+ calls, 99.9% success
1

Query trust score before calling

// Check skill reputation before payment
const trust = await upskill.getTrustScore(skillAddress);

// trust.tier: 'bronze' | 'silver' | 'gold' | 'diamond'
// trust.successRate: 0.0 - 1.0
// trust.totalCalls: number
// trust.stakedAmount: bigint
2

Set your threshold

// Only call skills that meet your standards
const MIN_TIER = 'silver';
const MIN_SUCCESS_RATE = 0.99;

if (trust.tier >= MIN_TIER && trust.successRate >= MIN_SUCCESS_RATE) {
  // Proceed with x402 payment
  const result = await paymentFetch(skillEndpoint);
} else {
  // Skip this skill, find a better one
  console.log('Skill does not meet trust requirements');
}
3

Middleware integration (optional)

import { wrapFetchWithTrust } from '@upskill/middleware';

// Wrap your fetch with trust-gating built in
const trustedFetch = wrapFetchWithTrust(paymentFetch, {
  minTier: 'silver',
  minSuccessRate: 0.99,
  onReject: (skill, trust) => {
    console.log(`Rejected ${skill}: tier=${trust.tier}`);
  }
});

// Now all calls are automatically trust-gated
const result = await trustedFetch(skillEndpoint);

🔌How to Integrate a Skill

1

Install the x402 client

npm install x402-fetch viem
2

Set up your wallet

import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const wallet = createWalletClient({
  account,
  chain: base,
  transport: http(),
});
3

Make a paid API call

import { wrapFetch } from 'x402-fetch';

const paymentFetch = wrapFetch(fetch, wallet);

const response = await paymentFetch(
  'https://market-analysis.up.railway.app/api/price?symbol=ETH'
);
const data = await response.json();
console.log(data.price);

📝How to List Your Skill

  1. 1

    Build your API

    Create an HTTP endpoint that returns 402 Payment Required with x402 payment details

  2. 2

    Use the x402 SDK

    Install @coinbase/x402 to handle payment verification

  3. 3

    Deploy

    Host on Railway, Vercel, or any platform

  4. 4

    Submit to marketplace

    Contact us to list your skill (coming soon: self-service listing)

  5. 5

    Stake $UPSKILL

    Back your skill with $UPSKILL to signal quality and build trust

💰x402 Payment Flow

1

Client calls skill endpoint without payment header

2

Server returns 402 with payment requirements (amount, recipient, network)

3

Client signs EIP-712 payment authorization

4

Client retries with X-Payment header containing signature

5

Server verifies payment via facilitator, returns data

6

Facilitator settles payment to skill provider's wallet

🔗Resources