# SkinsNode API Full Agent Context

> SkinsNode is a CS2 skin fulfillment API for stores, lootbox platforms, reward products, marketplaces, and skin apps.

Token estimate: about 2,900 tokens.

## Canonical Resources

- Site: https://skinsnode.com/
- API docs: https://skinsnode.com/docs
- API reference Markdown: https://skinsnode.com/docs/api-reference.md
- OpenAPI contract: https://skinsnode.com/openapi.json
- Agent prompt: https://skinsnode.com/docs/ai-agent-integration.md
- Brand facts: https://skinsnode.com/brand-facts.json
- Contact: https://t.me/tek9nino

## What SkinsNode Does

SkinsNode provides API infrastructure for CS2 skin sellers. It lets an approved client read a live account-scoped catalog, create customer skin orders, and track fulfillment with signed webhooks or polling. The integration is server-side because client credentials must stay private.

## Authentication

Authenticated routes require:

```http
x-client-id: <client id>
x-client-secret: <client secret>
```

Never expose `x-client-secret` to browser code, mobile apps, logs, analytics, or public repositories.

## API Endpoints

| Method | Path | Auth | Purpose |
| --- | --- | --- | --- |
| GET | `/v1/health` | No auth | Check API liveness. |
| GET | `/v1/wallet` | Client credentials | Read the authenticated prepaid balance. |
| GET | `/v1/catalog` | Client credentials | Read account-scoped CS2 skin inventory. |
| POST | `/v1/orders` | Client credentials | Create an asynchronous customer order. |
| GET | `/v1/orders/{externalId}` | Client credentials | Read the latest state for one order. |

## Order Creation

Required body:

```json
{
  "catalogItemId": "8d15e82b-21fe-4ec1-a37f-1e2e5edeb1fd",
  "expectedPrice": 1840,
  "externalId": "order_100042",
  "webhookUrl": "https://store.example/webhooks/orders",
  "tradeUrl": "https://steamcommunity.com/tradeoffer/new/?partner=123&token=abc"
}
```

Successful create calls return `202 Accepted` with status `accepted`. Use the store order ID as `externalId`; it acts as an idempotency key.

## Recommended Flow

1. Refresh `GET /v1/catalog` before showing or quoting inventory.
2. Confirm the chosen item still exists.
3. Collect the recipient Steam trade URL.
4. Submit `POST /v1/orders`.
5. Store the accepted order locally.
6. Prefer signed webhooks for updates.
7. Poll `GET /v1/orders/{externalId}` as a fallback.

## Webhooks

SkinsNode sends `order.updated` webhooks to the order `webhookUrl`.

Headers:

```http
x-event-type: order.updated
x-delivery-id: 01971d02-...
x-timestamp: 2026-04-25T12:36:12.000Z
x-signature: <hmac-sha256-hex>
```

Verify the signature by computing HMAC-SHA256 over:

```text
<x-timestamp>.<raw request body>
```

Use the same client secret from `x-client-secret` as the HMAC key.

## Statuses

Terminal statuses are `completed`, `failed`, `cancelled`, `expired`, and `reversed`.

Non-terminal statuses include `queued`, `processing`, `accepted`, `pending`, and `sent`.

## Error Codes

Handle `401`, `403`, `404`, and `422`. Known failure codes include `item_unavailable`, `price_changed`, `insufficient_funds`, and `cancelled`.