coal
coal

Sanctions Screening

Coal automatically screens every wallet address involved in a payment against international sanctions lists before processing the transaction.

How It Works

Coal queries the Chainalysis Sanctions Oracle — an on-chain smart contract deployed on Base mainnet that reflects OFAC, EU, UK, and UN sanctions lists in near real-time.

text
1Contract: 0x40C57923924B5c5c5455c48D93317139ADDaC8fb (Base mainnet)
2Method:   isSanctioned(address) → bool

The check happens before the checkout session is confirmed. If an address is flagged:

json
1HTTP/1.1 403 Forbidden
2

3{
4  "error": {
5    "code": "SANCTIONS_MATCH",
6    "message": "This address is on a sanctions list and cannot receive payments.",
7    "requestId": "req_abc123"
8  }
9}

Fail-Open Policy

Oracle availability

If the Chainalysis oracle is temporarily unavailable (network issue, RPC error), Coal fails open — the payment proceeds and a warning is written to the structured log. This prioritizes availability over blocking legitimate transactions during outages.

In a future release, merchants will be able to configure fail-closed behavior.

What Addresses Are Screened

ScenarioAddresses Checked
Direct checkoutCustomer's from wallet address
Split paymentsAll recipient addresses in the split config
Paywall accessAddress submitted in the pay request

The merchant's own payout address is not screened on every transaction (it is validated at account setup time).

Merchant Obligations

Coal's sanctions screening is a best-effort layer and does not substitute for your own compliance obligations. Depending on your jurisdiction, you may be required to:

  • Conduct additional KYC/AML checks for high-value transactions
  • File Suspicious Activity Reports (SARs)
  • Maintain transaction records for 5+ years
  • Obtain a money transmitter license

Consult a compliance attorney for advice specific to your business.

Covered Sanctions Lists

The Chainalysis oracle aggregates:

  • OFAC SDN — US Office of Foreign Assets Control Specially Designated Nationals
  • OFAC Consolidated — All OFAC programs
  • EU Sanctions — European Union restrictive measures
  • UK OFSI — Office of Financial Sanctions Implementation
  • UN Security Council — UN-mandated sanctions

Testing

In development (localhost), sanctions screening uses the same oracle as production. To test the blocked flow, use a known sanctioned address from the Chainalysis public test set — or mock the isAddressSanctioned function in your test suite:

typescript
1// vitest mock example
2vi.mock('@/lib/sanctions', () => ({
3  isAddressSanctioned: vi.fn().mockResolvedValue(true),
4}));