API Reference

Complete API documentation for the Paygrid clearing network

Base URL

All API requests are made to this base URL

https://api.paygrid.network

Authentication

All API requests require an API key

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Discovery API

Find and connect with financial institutions on the network

Lookup Institution

GET

/api/discovery/lookup/{institutionId}

Response Example

{
  "data": {
    "institutionId": "inst-bravo",
    "displayName": "BritPay Financial",
    "type": "bank",
    "endpoints": {
      "accord": "https://api.britpay.com/paygrid"
    },
    "publicKeys": {
      "primary": "0x1234567890abcdef..."
    },
    "supportedAssets": [
      "eip155:8453/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    ],
    "supportedChains": [
      "eip155:8453"
    ],
    "status": "active",
    "readiness": "ready"
  }
}

Error Handling

Error Response Format

All errors follow a consistent structure

{
  "error": {
    "code": "invalid_request",
    "message": "Validation failed",
    "http_status": 400,
    "details": {
      "field": "amount",
      "expected": "integer string"
    }
  }
}

Common Error Codes

invalid_requestInvalid request format or missing fields

unauthorizedMissing or invalid API key

forbiddenInstitution not ready or insufficient permissions

not_foundResource does not exist

rate_limitedToo many requests

Rate Limiting

Default Rate Limit100 requests per minute

Burst Limit200 requests per minute

Retry-After HeaderIncluded in 429 responses