cURL / Raw HTTP Quickstart

This guide demonstrates how to interact with an FX402-protected resource using plain HTTP — no SDKs, no frameworks.
Perfect for debugging, verifying server responses, or integrating into custom environments.

🧩 1. Request the Resource

Start by requesting a protected asset.
The server will respond with a 402 Payment Required response containing the R402 requirements.


curl -i https://fx402.xyz/api/memes/rare-001.png

Example response:


HTTP/1.1 402 Payment Required
Content-Type: application/json


{
  "standard": "x402",
  "profile": "r402/v1",
  "resource": "nft:solana:mint:9abc...xyz",
  "usage": {
    "tiers": [
      {
        "id": "1d",
        "label": "1 Day Access",
        "duration_seconds": 86400,
        "price": { "amount": "0.50", "currency": "USDC", "chain": "solana" }
      },
      {
        "id": "7d",
        "label": "1 Week Access",
        "duration_seconds": 604800,
        "price": { "amount": "2.00", "currency": "USDC", "chain": "solana" }
      }
    ],
    "modes": ["view", "remix"]
  },
  "pay_to": { "address": "SoLWallet111...", "chain": "solana" },
  "facilitator": "https://facilitator.fx402.xyz/settle",
  "nonce": "bf1c...e7",
  "expires_at": "2025-10-30T00:00:00Z"
}

💳 2. Make the Payment

Using your wallet or blockchain CLI (e.g., Solana CLI), send the payment to the provided address:


solana transfer SoLWallet111...xyz 2.00 --allow-unfunded-recipient --fee-payer mywallet.json

Once confirmed on-chain, copy the transaction signature (e.g., 4sJQd2cA...FyW).

🔁 3. Retry with Payment Proof

Now re-send your request with the proof of payment attached as JSON:


curl -i -X POST https://fx402.xyz/api/memes/rare-001.png \
  -H "Content-Type: application/json" \
  -d '{
        "standard": "x402",
        "profile": "r402/v1",
        "tier_id": "7d",
        "payment_proof": {
          "chain": "solana",
          "currency": "USDC",
          "tx": "4sJQd2cA...FyW"
        }
      }'

Example successful response:


HTTP/1.1 200 OK
Content-Type: application/json


{
  "profile": "r402/v1",
  "receipt": {
    "resource": "nft:solana:mint:9abc...xyz",
    "tier_id": "7d",
    "paid": { "amount": "2.00", "currency": "USDC" },
    "valid_from": "2025-10-29T00:00:00Z",
    "valid_until": "2025-11-05T00:00:00Z",
    "jwt": "<signed JWT>"
  }
}

🧾 4. Save Your Receipt

Save the JWT or the full receipt object locally.
This acts as your proof of license — you can re-use it for the same resource until valid_until expires.

Example:


echo "<signed JWT>" > fx402-receipt.jwt

You can present this JWT in future requests using a header:


curl -H "Authorization: Bearer $(cat fx402-receipt.jwt)" \
     https://fx402.xyz/api/memes/rare-001.png

🧠 5. Understanding the Flow

Step	Description
1️⃣	Request resource → server replies 402 Payment Required
2️⃣	Review JSON → pick a tier and note payment address
3️⃣	Make on-chain payment
4️⃣	Retry request with proof (tx ID, chain, currency)
5️⃣	Receive resource + signed receipt
6️⃣	Reuse receipt until expiration

🔐 6. Optional Verification

You can verify your JWT receipt offline using jwt-cli :


npm install -g jwt-cli
jwt decode fx402-receipt.jwt

Ensure:

valid_until is in the future
resource matches your target asset
issuer matches the expected facilitator

🧰 7. Useful Debug Tips

Scenario	Fix
Server keeps returning 402	Ensure your `payment_proof.tx` has confirmed on-chain.
Invalid JWT signature	The facilitator’s signing key may have rotated; refresh 402.
Access expired	Re-run payment flow with new tier selection.
409 Conflict	The same nonce was reused — request a fresh 402 payload.

✅ Summary

FX402 works with any HTTP client — you just need to send JSON.
402 → Pay → Retry → Unlock is the universal pattern.
Receipts (JWTs) let you re-access without paying again.
Facilitators verify transactions and sign proofs.