Creating Skills

Dashboard setup

1. Sign up at 402.md and create a developer account
2. On first login you receive two keys:
   • API key (sk_xxx) — server-side authentication. Hashed on our end, shown only once
   • Publishable key (pk_xxx) — client-side, used by the checkout widget

Keep your API key safe. If you lose it, you'll need to rotate it from the dashboard.

Create a skill

Go to Dashboard → Skills → New Skill and fill in:

Skill types

Hold periods

The holdPeriodHours field controls how long funds stay in escrow before settling to your wallet. Defaults vary by type:

Add endpoints

Each skill has one or more priced endpoints. For each endpoint:

Endpoints are appended to the skill's base URL. For a skill named sentiment-api, endpoint /analyze becomes:

https://api.402.md/api/v1/skills/sentiment-api/analyze

SKILL.md

When you create a skill and add endpoints, 402.md auto-generates a SKILL.md file. This file describes your skill in a format that AI agents can read and understand.

The generated format uses YAML frontmatter:

---
name: sentiment-api
base_url: https://api.402.md/api/v1/skills/sentiment-api
version: "1.0.0"
description: "Analyze sentiment of any text"
endpoints:
    - path: /analyze
      method: POST
      price: "$0.05"
      description: "Analyze text sentiment"
---

# Sentiment Analysis API

Analyze sentiment of any text

## How to pay

All endpoints below are protected by the **x402 payment protocol**...

## Endpoints

### POST /analyze — $0.05

Analyze text sentiment

**Request:**
`POST https://api.402.md/api/v1/skills/sentiment-api/analyze`

This endpoint is x402-protected...

The SKILL.md is regenerated whenever you add, update, or deactivate endpoints. You can also edit it manually from the dashboard.

Agents fetch this file to discover your endpoints and prices before making paid calls.

Skill lifecycle

After creation, skills go through validation:

PENDING_VALIDATION → ACTIVE
                   → VALIDATION_FAILED (fix and retry)
ACTIVE → SUSPENDED (policy violation or manual)
ACTIVE → ARCHIVED (by developer)

Validation checks:

• apiBaseUrl must use HTTPS in production
• Each endpoint must respond to a HEAD request
• Endpoint latency must be under 5,000ms

If validation fails, the statusReason field explains what went wrong.

Health checks

402.md periodically pings your endpoints. Each endpoint has an isHealthy flag that updates automatically. Unhealthy endpoints are still listed but may be flagged to agents.

Revenue flow

Agent pays USDC → 402.md verifies payment → 5% platform fee deducted → escrow
    → hold period expires → settlement to your developer wallet

For API and Content types with 0-hour hold, settlement is near-instant. For Products and Services, funds are held in escrow until the hold period expires.

API keys

PROXY vs TICKET mode

PROXY mode (default): Agent requests go through 402.md infrastructure. 402.md verifies payment and forwards the request to your API. You don't need to run any middleware.

TICKET mode: After payment, the agent receives a signed JWT ticket and calls your API directly. You verify the ticket using the @402md/gateway middleware. This gives you full control over request handling.