Use Cases - BSV X402 Accessible Facilitator

This document contains practical examples of how to use the BSV X402 Facilitator with universal accessibility.

Table of Contents

Verify Transaction (User Story 1)

Example 1: Successful Verification

Request:

curl -X POST https://your-facilitator.com/verify \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "network": "bsv-testnet",
      "scheme": "exact",
      "txHex": "0100000001..."
    },
    "paymentRequirements": {
      "payTo": "mtZBZacoN7S2KW6aP6YXm9FMfNYFztS1oB",
      "maxAmountRequired": "500"
    }
  }'

Response (200 OK):

{
  "data": {
    "isValid": true,
    "verifiedAt": "2025-11-28T08:00:00Z"
  },
  "accessibility": {
    "plainLanguage": "The payment is valid",
    "explanation": "The transaction meets all requirements: the amount of 500 satoshis matches the requested amount and the destination address is correct.",
    "stepByStep": [
      "The sent amount (500 satoshis) matches the required amount",
      "The destination address is correct",
      "The transaction is ready to be processed"
    ],
    "hints": {
      "nextSteps": "You can proceed to send the transaction using the /settle endpoint"
    },
    "language": "en",
    "audioFriendly": true,
    "cognitiveLevel": "simple"
  }
}

Example 2: Incorrect Amount

Request:

curl -X POST https://your-facilitator.com/verify \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "network": "bsv-testnet",
      "scheme": "exact",
      "txHex": "0100000001..."
    },
    "paymentRequirements": {
      "payTo": "mtZBZacoN7S2KW6aP6YXm9FMfNYFztS1oB",
      "maxAmountRequired": "1000"
    }
  }'

Response (200 OK):

{
  "data": {
    "isValid": false,
    "invalidReason": "invalid_amount"
  },
  "accessibility": {
    "plainLanguage": "The sent amount is incorrect",
    "explanation": "Expected 1000 satoshis but received 500 satoshis. Please verify the amount and create a new transaction.",
    "stepByStep": [
      "Check that the amount is exactly 1000 satoshis",
      "Create a new transaction with the correct amount",
      "Try verifying again"
    ],
    "hints": {
      "commonMistakes": [
        "Confusing satoshis with BSV (1 BSV = 100,000,000 satoshis)",
        "Not including transaction fees in the calculation"
      ]
    },
    "language": "en",
    "audioFriendly": true,
    "cognitiveLevel": "simple"
  }
}

Example 3: Invalid Address

Request:

curl -X POST https://your-facilitator.com/verify \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "network": "bsv-testnet",
      "scheme": "exact",
      "txHex": "0100000001..."
    },
    "paymentRequirements": {
      "payTo": "1MainnetAddress...",
      "maxAmountRequired": "500"
    }
  }'

Response (200 OK):

{
  "data": {
    "isValid": false,
    "invalidReason": "invalid_address"
  },
  "accessibility": {
    "plainLanguage": "The destination address is incorrect",
    "explanation": "The provided address does not match the expected address or is not valid for testnet. Expected mtZBZacoN7S2KW6aP6YXm9FMfNYFztS1oB.",
    "stepByStep": [
      "Verify that you are using a testnet address",
      "Confirm that the address matches the requested one",
      "Create a new transaction with the correct address"
    ],
    "hints": {
      "commonMistakes": [
        "Using mainnet address instead of testnet",
        "Copying the address incorrectly (missing/extra character)"
      ]
    },
    "language": "en",
    "audioFriendly": true,
    "cognitiveLevel": "simple"
  }
}

Process Payment (User Story 2)

Example 4: Successful Broadcast

Request:

curl -X POST https://your-facilitator.com/settle \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "network": "bsv-testnet",
      "scheme": "exact",
      "txHex": "0100000001..."
    },
    "paymentRequirements": {
      "payTo": "mtZBZacoN7S2KW6aP6YXm9FMfNYFztS1oB",
      "maxAmountRequired": "500"
    }
  }'

Response (200 OK):

{
  "data": {
    "success": true,
    "transaction": "abc123def456...",
    "broadcastedAt": "2025-11-28T08:00:00Z"
  },
  "accessibility": {
    "plainLanguage": "Your payment was processed successfully",
    "explanation": "The transaction was successfully sent to the BSV testnet network. Your transaction identifier is abc123def456...",
    "stepByStep": [
      "The transaction was validated",
      "It was sent to the BSV testnet network",
      "It was accepted by the network"
    ],
    "hints": {
      "nextSteps": "Save the transaction ID (abc123def456...) as proof"
    },
    "language": "en",
    "audioFriendly": true,
    "cognitiveLevel": "simple"
  }
}

Example 5: Network Error

Request:

curl -X POST https://your-facilitator.com/settle \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "network": "bsv-testnet",
      "scheme": "exact",
      "txHex": "0100000001..."
    },
    "paymentRequirements": {
      "payTo": "mtZBZacoN7S2KW6aP6YXm9FMfNYFztS1oB",
      "maxAmountRequired": "500"
    }
  }'

Response (200 OK):

{
  "data": {
    "success": false,
    "errorReason": "network_error"
  },
  "accessibility": {
    "plainLanguage": "Could not send the transaction to the network",
    "explanation": "There was a problem trying to communicate with the BSV network. This may be due to temporary connectivity issues.",
    "stepByStep": [
      "Verify your internet connection",
      "Wait a few minutes",
      "Try sending the transaction again"
    ],
    "hints": {
      "ifError": "If the error persists after several attempts, contact support",
      "nextSteps": "You can retry sending with the same txHex"
    },
    "language": "en",
    "audioFriendly": true,
    "cognitiveLevel": "medium"
  }
}

Example 6: Transaction Already Processed

Request:

curl -X POST https://your-facilitator.com/settle \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "network": "bsv-testnet",
      "scheme": "exact",
      "txHex": "0100000001..."
    },
    "paymentRequirements": {
      "payTo": "mtZBZacoN7S2KW6aP6YXm9FMfNYFztS1oB",
      "maxAmountRequired": "500"
    }
  }'

Response (200 OK):

{
  "data": {
    "success": false,
    "errorReason": "already_broadcast",
    "transaction": "abc123def456..."
  },
  "accessibility": {
    "plainLanguage": "This transaction has already been processed",
    "explanation": "The transaction with ID abc123def456... already exists on the BSV network. There is no need to send it again.",
    "stepByStep": [
      "The transaction is already on the blockchain",
      "You can verify its status with the ID: abc123def456...",
      "You don't need to do anything else"
    ],
    "hints": {
      "nextSteps": "Use the transaction ID to check its status on a block explorer"
    },
    "language": "en",
    "audioFriendly": true,
    "cognitiveLevel": "simple"
  }
}

Accessible Response Structure

All facilitator responses include an accessibility object with information in clear Spanish:

{
  "data": { /* Endpoint-specific data */ },
  "accessibility": {
    "plainLanguage": string,      // Concise message (≤100 characters)
    "explanation": string,         // Detailed description (≤300 characters)
    "stepByStep": string[],        // Steps in order (≤5 items, 80 chars each)
    "hints": {
      "ifError": string,           // What to do if there's an error
      "commonMistakes": string[],  // Common mistakes to avoid
      "nextSteps": string          // Suggested next action
    },
    "language": "en",              // Language (always Spanish)
    "audioFriendly": boolean,      // Compatible with screen readers
    "cognitiveLevel": "simple" | "medium" | "advanced"
  }
}

Length Limits

  • plainLanguage: maximum 100 characters
  • explanation: maximum 300 characters
  • stepByStep: maximum 5 items of 80 characters each
  • No technical jargon (do not use terms like “API”, “JSON”, “HTTP”, etc.)

Error Handling

Validation Error (400)

Request with malformed JSON:

curl -X POST https://your-facilitator.com/verify \
  -H "Content-Type: application/json" \
  -d 'invalid-json{'

Response (400 Bad Request):

{
  "error": "Malformed JSON in request body",
  "metadata": {
    "accessible": {
      "plainLanguage": "The provided data is incorrect",
      "explanation": "The information you entered does not meet the necessary requirements. Please verify that all fields are complete and valid.",
      "stepByStep": [
        "Check that all fields are complete",
        "Verify that the data is in the correct format",
        "Try sending the information again"
      ],
      "hints": {
        "ifError": "Review the error details and contact support if necessary",
        "nextSteps": "Try performing the operation again"
      },
      "language": "en",
      "audioFriendly": true,
      "cognitiveLevel": "simple"
    },
    "i18n": {
      "lang": "es"
    }
  },
  "status": 400
}

Server Error (500)

Response (500 Internal Server Error):

{
  "error": "System error",
  "metadata": {
    "accessible": {
      "plainLanguage": "An unexpected problem occurred",
      "explanation": "The system encountered an error it could not process. This problem has been logged and will be reviewed by the technical team.",
      "stepByStep": [
        "Try performing the action again",
        "If the error persists, wait a few minutes",
        "Contact support if the problem continues"
      ],
      "hints": {
        "ifError": "Review the error details and contact support if necessary",
        "nextSteps": "Try performing the operation again"
      },
      "language": "en",
      "audioFriendly": true,
      "cognitiveLevel": "simple"
    },
    "i18n": {
      "lang": "es"
    }
  },
  "status": 500
}

Verify Supported Networks

Request:

curl https://your-facilitator.com/

Response (200 OK):

{
  "data": {
    "networks": ["bsv-testnet"]
  },
  "accessibility": {
    "plainLanguage": "Supported networks: bsv-testnet",
    "explanation": "This facilitator supports payments on the BSV test network (testnet). You can send test transactions without using real money.",
    "stepByStep": [
      "Verify that your transaction uses the bsv-testnet network",
      "Get testnet satoshis from a faucet",
      "Use the /verify and /settle endpoints to process payments"
    ],
    "hints": {
      "nextSteps": "Check the documentation to see usage examples"
    },
    "language": "en",
    "audioFriendly": true,
    "cognitiveLevel": "simple"
  }
}

CORS and LLM Clients

This facilitator is configured to accept requests from any origin (Access-Control-Allow-Origin: *), which allows integrations with:

  • Claude Desktop
  • ChatGPT
  • Other LLM clients
  • Web and mobile applications

Example request from browser:

fetch('https://your-facilitator.com/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    payload: {
      network: 'bsv-testnet',
      scheme: 'exact',
      txHex: '0100000001...'
    },
    paymentRequirements: {
      payTo: 'mtZBZacoN7S2KW6aP6YXm9FMfNYFztS1oB',
      maxAmountRequired: '500'
    }
  })
})
.then(response => response.json())
.then(data => {
  console.log('Result:', data.accessibility.plainLanguage);
  console.log('Explanation:', data.accessibility.explanation);
  console.log('Steps:', data.accessibility.stepByStep);
});

Important Notes

  1. Test network: This facilitator operates on bsv-testnet, do not use real money.
  2. Plain language: All responses are in clear language, chosen by the user, without technical jargon.
  3. Accessibility: Responses are optimized for screen readers and people with cognitive disabilities.
  4. No sensitive information: Errors never expose passwords, private keys, or other sensitive information.