# three.ws Cosmetic Purchase

> three.ws Cosmetic Purchase is a paid API for AI agents from three.ws, paid per call via x402, $0.5/call, status unknown (last checked 2026-09-15).

Purchases a premium cosmetic item for a 3D AI agent avatar and grants ownership to a specified account via micropayment

## Facts

- Endpoint: GET https://three.ws/api/x402/cosmetic-purchase
- Price: $0.5/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/three-ws-cosmetic-purchase-76e52e48
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_Cq87Ldpkjc9Y7sRW0-OGs

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability three-ws-cosmetic-purchase-76e52e48
```

Example prompt: Buy the 'Midnight' legendary skin cosmetic (id: skin-midnight) for my three.ws AI agent account g_5f3c9a21b8 — charge 0.5 USDC and grant ownership to that guest account.

## When to prefer this

Use this endpoint when you need to programmatically purchase and grant a premium cosmetic to a specific 3D AI agent avatar account on three.ws, paying via x402 USDC micropayment. Prefer this over manual storefront flows when automating avatar customization or building agent onboarding pipelines that include cosmetic unlocks.

## Known failure modes

- Cosmetic ID not found in catalog — returns error if 'id' does not match a valid premium cosmetic
- Account not found or invalid — returns error if account string is malformed or unrecognized
- Payment failure — insufficient USDC balance or x402 payment authorization fails
- Cosmetic already owned — endpoint may return owned:true but newlyOwned:false if already purchased
- Invalid account format — account must be a valid Solana wallet address or g_… guest ID

## How this service works

Make a 3D AI agent from a selfie in 60 seconds. Drop one HTML tag to embed it on any website. Agents think on IBM watsonx.ai (Granite); optionally charge per chat with built-in micropayments.

## Output

Returns a JSON object confirming the purchase: cosmetic ID, name, slot type, rarity, the account it was granted to, the paying wallet address, whether it was newly acquired, the payment amount in atomics, the network used, and creator revenue split details (creator wallet, basis points, payout transaction).

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "required": [
      "id",
      "account"
     ],
     "properties": {
      "id": {
       "type": "string",
       "maxLength": 64,
       "minLength": 1,
       "description": "Premium cosmetic id from /api/cosmetics/catalog."
      },
      "account": {
       "type": "string",
       "maxLength": 64,
       "minLength": 3,
       "description": "The account the cosmetic is granted to — a Solana wallet address or a guest id (g_…). Ownership is keyed here, not on the paying wallet."
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "required": [
      "ok",
      "id",
      "name",
      "slot",
      "rarity",
      "account",
      "owned"
     ],
     "properties": {
      "id": {
       "type": "string"
      },
      "ok": {
       "type": "boolean",
       "const": true
      },
      "coin": {
       "type": [
        "string",
        "null"
       ]
      },
      "name": {
       "type": "string"
      },
      "slot": {
       "type": "string"
      },
      "asset": {
       "type": [
        "string",
        "null"
       ]
      },
      "owned": {
       "type": "boolean",
       "const": true
      },
      "payer": {
       "type": [
        "string",
        "null"
       ]
      },
      "split": {
       "type": [
        "object",
        "null"
       ],
       "properties": {
        "payoutTx": {
         "type": [
          "string",
          "null"
         ]
        },
        "creatorBps": {
         "type": "number"
        },
        "payoutStatus": {
         "type": "string"
        },
        "creatorWallet": {
         "type": [
          "string",
          "null"
         ]
        },
        "creatorCutAtomics": {
         "type": "string"
        }
       }
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "id": "skin-midnight",
  "ok": true,
  "name": "Midnight",
  "slot": "skin",
  "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "owned": true,
  "payer": "wwwPqsM4N7T9J69tB82nLyzxqsH159j4orftLTQfUGV",
  "rarity": "legendary",
  "account": "g_5f3c9a21b8",
  "network": "solana",
  "newlyOwned": true,
  "amountAtomics": "3000000"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/three-ws-cosmetic-purchase-76e52e48/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from three.ws](https://www.zero.xyz/host/three.ws/llms.txt)