Skip to main content

​
Endpoints

Detailed reference for each Prism Gateway API endpoint. All endpoints use the base URL https://prism-gw.fd.xyz and require an API key in the X-API-Key header. See Introduction for authentication and error handling details.

​
Create Charge

Create a new payment charge. Returns the charge details including payment requirements that an AI agent uses to submit payment. 
POST /v1/charges

​
Request Body

FieldTypeRequiredDescription
amountstringYesAmount in USD (e.g., "0.50")
tokenstringYesToken symbol (FDUSD or USDC)
chainstringYesChain identifier (base, ethereum, bsc, arbitrum)
descriptionstringNoHuman-readable description
metadataobjectNoArbitrary key-value metadata
curl -X POST https://prism-gw.fd.xyz/v1/charges \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "0.50",
    "token": "USDC",
    "chain": "base",
    "description": "Premium API access",
    "metadata": {
      "endpoint": "/api/premium/data",
      "request_id": "req_123"
    }
  }'

​
Response

{
  "success": true,
  "data": {
    "id": "ch_abc123def456",
    "amount": "500000",
    "token": "USDC",
    "chain": "base",
    "status": "pending",
    "payment_address": "0xMerchantWallet1234567890abcdef1234567890ab",
    "description": "Premium API access",
    "metadata": {
      "endpoint": "/api/premium/data",
      "request_id": "req_123"
    },
    "expires_at": "2025-01-15T10:35:00Z",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

​
Get Charge

Retrieve details of a specific charge, including its current status and payment information. 
GET /v1/charges/:id

​
Path Parameters

ParameterTypeDescription
idstringCharge ID (ch_...)
curl https://prism-gw.fd.xyz/v1/charges/ch_abc123def456 \
  -H "X-API-Key: your-api-key"

​
Response

{
  "success": true,
  "data": {
    "id": "ch_abc123def456",
    "amount": "500000",
    "token": "USDC",
    "chain": "base",
    "status": "completed",
    "payment_address": "0xMerchantWallet1234567890abcdef1234567890ab",
    "tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "from": "0xAgentWallet1234567890abcdef1234567890abcdef",
    "paid_at": "2025-01-15T10:30:45Z",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

​
Charge Statuses

StatusDescription
pendingCharge created, awaiting payment
completedPayment verified and settled on-chain
failedPayment failed verification
expiredCharge expired before payment was received
cancelledCharge manually cancelled

​
Cancel Charge

Cancel a pending charge. Only works for charges with pending status — charges that have already been paid cannot be cancelled. 
DELETE /v1/charges/:id

curl -X DELETE https://prism-gw.fd.xyz/v1/charges/ch_abc123def456 \
  -H "X-API-Key: your-api-key"

​
Response

{
  "success": true,
  "data": {
    "id": "ch_abc123def456",
    "status": "cancelled"
  }
}
Returns 400 if the charge is not in pending status.

​
Register Webhook

Register a new webhook endpoint to receive payment event notifications. See Webhooks for implementation details and signature verification. 
POST /v1/webhooks

​
Request Body

FieldTypeRequiredDescription
urlstringYesHTTPS URL to receive webhook POSTs
eventsarrayYesEvent types to subscribe to
curl -X POST https://prism-gw.fd.xyz/v1/webhooks \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/prism",
    "events": ["payment.completed", "payment.failed", "settlement.completed"]
  }'

​
Response

{
  "success": true,
  "data": {
    "id": "wh_xyz789ghi012",
    "url": "https://yourapp.com/webhooks/prism",
    "events": ["payment.completed", "payment.failed", "settlement.completed"],
    "signing_secret": "whsec_abc123...",
    "created_at": "2025-01-15T10:00:00Z"
  }
}
Store the signing_secret securely — it’s only returned once at creation time. Use it to verify webhook signatures.

​
List Transactions

Retrieve a paginated list of transactions with optional filtering. 
GET /v1/transactions

​
Query Parameters

ParameterTypeDefaultDescription
limitnumber20Max results per page (max: 100)
offsetnumber0Pagination offset
statusstring—Filter by status (completed, failed, etc.)
chainstring—Filter by chain (base, ethereum, etc.)
fromstring—Start date, ISO 8601
tostring—End date, ISO 8601
curl "https://prism-gw.fd.xyz/v1/transactions?status=completed&chain=base&limit=50" \
  -H "X-API-Key: your-api-key"

​
Response

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "tx_abc123",
        "charge_id": "ch_abc123def456",
        "amount": "500000",
        "token": "USDC",
        "chain": "base",
        "status": "completed",
        "from": "0xAgentWallet1234567890abcdef1234567890abcdef",
        "to": "0xMerchantWallet1234567890abcdef1234567890ab",
        "tx_hash": "0x1234567890abcdef...",
        "created_at": "2025-01-15T10:30:45Z"
      }
    ],
    "total": 142,
    "limit": 50,
    "offset": 0
  }
}