API

Updated on Apr 9

Access service data via our API.

All endpoints should be prefixed with /api/v1/.

The endpoints source code is available on the /web/src/actions/api/index.ts file.

Attribution: You MUST credit KYCnot.me if you use data from this API.

Authentication

All API requests require an API key. Include it in one of these headers:

Authorization: Bearer kycnot_your_key_here

X-Api-Key: kycnot_your_key_here

To get an API key, an admin must first grant you access. Once enabled, you can create a key from your account settings.

Requests without a valid key receive a 401 response:

{
  "error": "API key required"
}

`QUERY` `/service/get`

Fetches details for a single service by various lookup criteria.

Request Parameters

Parameter	Type	Required	Description
`id`	number	No*	Service ID
`slug`	string	No*	Service URL slug (lowercase letters, numbers, and hyphens only)
`url`	string	No*	Service URL. May be web, onion, or i2p. May just be a domain or a full URL.

* At least one of the marked parameters is required.

Response Format

type ServiceResponse = {
  id: number
  slug: string
  name: string
  description: string
  serviceVisibility: 'PUBLIC' | 'ARCHIVED' | 'UNLISTED'
  verificationStatus: 'VERIFICATION_SUCCESS' | 'APPROVED' | 'COMMUNITY_CONTRIBUTED' | 'VERIFICATION_FAILED'
  verificationStatusInfo: {
    value: 'VERIFICATION_SUCCESS' | 'APPROVED' | 'COMMUNITY_CONTRIBUTED' | 'VERIFICATION_FAILED'
    slug: string
    label: string
    labelShort: string
    description: string
  }
  verifiedAt: Date | null
  approvedAt: Date | null
  kycLevel: 0 | 1 | 2 | 3 | 4
  kycLevelInfo: {
    value: 0 | 1 | 2 | 3 | 4
    name: string
    description: string
  }
  /** Markdown. Per-service narrative on nuances of KYC/AML/refund policy. */
  kycPolicyMd: string | null
  /** KYC-category attributes attached to the service (e.g. "depends-on-partners", "own-liquidity"). */
  kycAttributes: {
    slug: string
    title: string
    description: string
    type: 'GOOD' | 'BAD' | 'WARNING' | 'INFO'
    privacyPoints: number
  }[]
  categories: {
    name: string
    slug: string
  }[]
  listedAt: Date
  serviceUrls: string[]
  tosUrls: string[]
  kycnotmeUrl: `https://kycnot.me/service/${service.slug}`
}

KYC Levels

0: Guaranteed no KYC - Terms explicitly state KYC will never be requested.
1: No KYC mention - No mention of current or future KYC requirements.
2: Rare KYC - No routine KYC, but may request it or block funds if compelled by authorities, legal orders, or internal risk review. Refunds are subject to policies.
3: Shotgun KYC - May request KYC or block funds mid-flow, typically via AML checks, transaction limits, or liquidity partner rules. Refunds are subject to policies.
4: Mandatory KYC - Required for key features, and may be required arbitrarily at any time.

Verification Status

VERIFICATION_SUCCESS: Passed repeated checks over time and showed consistent behavior.
APPROVED: Passed limited recent checks and met our approval threshold.
COMMUNITY_CONTRIBUTED: Listed, but not yet reviewed by the team.
VERIFICATION_FAILED: Failed review or shows serious unresolved risk.

Service Visibility

PUBLIC: Listed in search and browse.
UNLISTED: Unlisted service, only accessible via direct link and won't appear in searches.
ARCHIVED: Archived service, no longer exists or ceased operations. Information may be outdated.

Examples

Request

curl -X QUERY https://kycnot.me/api/v1/service/get \
  -H "Authorization: Bearer kycnot_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-example-service"}'

Response

{
  "id": 123,
  "name": "My Example Service",
  "description": "This is a description of my example service",
  "slug": "my-example-service",
  "serviceVisibility": "PUBLIC",
  "verificationStatus": "VERIFICATION_SUCCESS",
  "verificationStatusInfo": {
    "value": "VERIFICATION_SUCCESS",
    "slug": "verified",
    "label": "Verified",
    "labelShort": "Verified",
    "description": "Thoroughly tested and verified by the team. But things might change, this is not a guarantee."
  },
  "verifiedAt": "2025-06-14T11:02:39.294Z",
  "approvedAt": "2025-05-31T19:09:18.043Z",
  "kycLevel": 0,
  "kycLevelInfo": {
    "value": 0,
    "name": "Guaranteed no KYC",
    "description": "Terms explicitly state KYC will never be requested."
  },
  "kycPolicyMd": null,
  "kycAttributes": [
    {
      "slug": "own-liquidity",
      "title": "Uses own liquidity",
      "description": "The service runs its own liquidity, so there is no third-party LP that could independently demand KYC or block funds.",
      "type": "GOOD",
      "privacyPoints": 5
    }
  ],
  "categories": [
    {
      "name": "Exchange",
      "slug": "exchange"
    }
  ],
  "listedAt": "2025-04-20T07:12:29.393Z",
  "serviceUrls": [
    "https://example.com",
    "http://c9ikae0fdidzh1ufrzp022e5uqfvz6ofxlkycz59cvo6fdxjgx7ekl9e.onion"
  ],
  "tosUrls": ["https://example.com/terms-of-service"],
  "kycnotmeUrl": "https://kycnot.me/service/my-example-service"
}

Error Responses

404 Not Found: Service not found

{
  "error": "Service not found"
}

400 Bad Request: Invalid input parameters

{
  "error": "Validation error message"
}

500 Internal Server Error: Server error

{
  "error": "Internal server error"
}

API