API Reference

Base URL

https://facilitator.ivorypay.io

All x402 endpoints are under:

https://facilitator.ivorypay.io/api/x402

Authentication

All requests require your merchant API key in the Authorization header:

Authorization: <your-merchant-api-key>

No Bearer prefix — send the raw key value.

Headers

Header	Required	Description
Authorization	Yes — all endpoints	Your merchant API key.
Content-Type	Yes — endpoints with a JSON body	Set to application/json.
payment-signature	Yes — /submit only	Base64-encoded X402SignaturePayload JSON.

---

POST /api/x402/initiate

Initiates an x402 payment challenge for a protected resource. Returns a PAYMENT-REQUIRED payload describing the payment terms the payer must agree to.

Request Body

{
  "amount": 0.01,
  "token": "USDC",
  "network": "BASE_MAINNET",
  "resourceUrl": "https://yourapp.com/premium-content",
  "resourcesDescription": "Access to premium content"
}

Field Reference

Field	Type	Rules	Description
amount	number	Positive	Amount in decimal token units. 0.01 = 1 cent for 2-decimal tokens.
token	string	See Supported Assets	Token to pay with.
network	string	See Supported Assets	Network to pay on.
resourceUrl	string	Non-empty	URL of the resource being paid for.
resourcesDescription	string	Non-empty	Human-readable description of the resource.

Response — 201

{
  "statusCode": 402,
  "headers": {
    "Content-Type": "application/json",
    "PAYMENT-REQUIRED": "<base64-encoded-json>"
  },
  "body": {
    "x402Version": 2,
    "error": "PAYMENT-SIGNATURE header is required",
    "resource": {
      "url": "https://yourapp.com/premium-content",
      "description": "Access to premium content",
      "mimeType": "application/json"
    },
    "accepts": [
      {
        "scheme": "exact",
        "network": "eip155:8453",
        "amount": "0.01",
        "asset": "0xTokenContractAddress",
        "payTo": "0xFacilitatorAddress",
        "maxTimeoutSeconds": 60,
        "extra": {
          "name": "USDC",
          "version": "2"
        }
      }
    ]
  }
}

Decode PAYMENT-REQUIRED with:

const paymentRequired = JSON.parse(
  Buffer.from(response.headers['PAYMENT-REQUIRED'], 'base64').toString('utf8')
);

---

POST /api/x402/build

Builds the EIP-712 typed data hash on the server and returns it ready to sign. The server selects the correct strategy (EIP-3009 or Permit2) based on the deposit's chain and token. You must call this endpoint for Permit2 payments to obtain the spender address.

Request Body

{
  "to": "0xFacilitatorPayToAddress",
  "from": "0xPayerWalletAddress",
  "nonce": "0xRandom32ByteHex",
  "validBefore": 1700000060
}

Field Reference

Field	Type	Rules	Description
to	string	Ethereum address	The payTo address from the accepted payment option.
from	string	Ethereum address	The payer's wallet address.
nonce	string	Non-empty hex string	A unique random hex value. Generate with ethers.hexlify(ethers.randomBytes(32)).
validBefore	number	≥ 0	Unix timestamp after which the authorization expires. Set to now + maxTimeoutSeconds.

Response — 201

{
  "typedDataHash": "0xComputedEIP712Hash",
  "from": "0xPayerWalletAddress",
  "to": "0xFacilitatorPayToAddress",
  "amount": 0.01,
  "chain": "BSC_MAINNET",
  "token": "USDT",
  "validAfter": 1700000000,
  "spender": "0xGasPayerVaultAddress"
}

Response Field Reference

Field	Description
typedDataHash	The EIP-712 hash to sign with the payer's private key.
chain	The chain the deposit is on. Cross-reference with Supported Assets to determine the signing strategy.
token	The token the deposit expects.
validAfter	Earliest unix timestamp the authorization is valid. Use this when building the payment-signature header.
spender	The gas-payer vault EOA. Required for Permit2 signing — must be included as the spender field in the Permit2 PermitTransferFrom message. Ignored for EIP-3009.

---

POST /api/x402/submit

Submits a signed x402 authorization to initiate the on-chain transfer. Requires a payment-signature header containing the base64-encoded signed payload.

Headers

Authorization: <your-merchant-api-key>
payment-signature: <base64-encoded-X402SignaturePayload>

Signature Payload Structure (before base64 encoding)

{
  "x402Version": 2,
  "resource": {
    "url": "https://yourapp.com/premium-content",
    "description": "Access to premium content",
    "mimeType": "application/json"
  },
  "accepted": {
    "scheme": "exact",
    "network": "eip155:56",
    "amount": "0.01",
    "asset": "0xTokenContractAddress",
    "payTo": "0xFacilitatorAddress",
    "maxTimeoutSeconds": 60,
    "extra": {
      "name": "USDT",
      "version": "2"
    }
  },
  "payload": {
    "signature": "0x<65-byte-hex-r+s+v>",
    "authorization": {
      "from": "0xPayerAddress",
      "to": "0xFacilitatorAddress",
      "value": "0.01",
      "validAfter": "1700000000",
      "validBefore": "1700000060",
      "nonce": "0xRandom32ByteHex"
    }
  }
}

Signature encoding: The signature field must be a 0x-prefixed 65-byte hex string in the format r[32] + s[32] + v[1]. This encoding is the same for both EIP-3009 and Permit2.

const sig = wallet.signingKey.sign(typedDataHash);
const signature = '0x' + sig.r.slice(2) + sig.s.slice(2) + Buffer.from([sig.v]).toString('hex');

Response — 201

{
  "sessionId": "sess_abc123"
}

---

POST /api/x402/verify/:reference

Verifies a payment reference and returns on-chain proof.

Path Parameters

Parameter	Description
reference	The sessionId returned by /submit.

Response — 201

{
  "statusCode": 200,
  "headers": {
    "Content-Type": "application/json",
    "PAYMENT-RESPONSE": "<base64-encoded-json>"
  }
}

Decoded shape:

{
  "success": true,
  "transaction": "0xOnChainTxHash",
  "network": "eip155:56",
  "payer": "0xPayerAddress"
}

---

Error Responses

Condition	Status	Message
Missing Authorization header	400	Please provide your api key
Missing payment-signature on /submit	400	PAYMENT-SIGNATURE header is required
Multiple payment-signature values	400	PAYMENT-SIGNATURE header must be a single value
Insufficient Permit2 allowance	400	x402: insufficient Permit2 allowance — sender must approve Permit2 contract
Invalid request body field	400	Validation error per field