Skip to content

API reference

API

API reference

Canonical origin https://api.fiscal402.com. Production ingest is POST /settlements.

Canonical origin: https://api.fiscal402.com. Authenticate ingest with X-Fiscal402-Key. Amounts are decimal strings. Timestamps are ISO-8601 UTC. Countries are ISO 3166-1 alpha-2. Networks use CAIP-2 (eip155:1).

OpenAPI: https://api.fiscal402.com/openapi.json.

POST /settlements

PRODUCTION x402 v2 exact. Records a settled transfer. Optional Idempotency-Key. Returns 201 with custody always none. Sync: the 201 body is the fiscal record. The receipt is available immediately at GET /v1/receipts/rcpt_<id>.

FieldTypeRequiredSourceExample
amountUsdcdecimal stringyessettlement1.00
txHashstringyessettlement0x…
timestampISO-8601yessettlement2026-09-10T12:00:00.000Z
payerWalletstringyessettlement0xPAYER
receiverWalletstringyessettlement0xPAY_TO
networkCAIP-2yessettlementeip155:1
assetstringnosettlementUSDC
schemestringnosettlementexact
consumerCountryISO 3166-1no*merchant_attestedDE
consumerVatNumberstringnomerchant_attestedDE…
consumerNamestringnomerchant_attestedBuyer GmbH

*Attest consumerCountry for EU VAT. Missing country is PENDING_MANUAL_REVIEW, not 0% VAT. Seller establishment is account data, not a POST field.

POST /settlements

POST https://api.fiscal402.com/settlements
Content-Type: application/json
X-Fiscal402-Key: $FISCAL402_API_KEY
Idempotency-Key: acme-nl-de-1

{
  "amountUsdc": "1.00",
  "txHash": "0xYOUR_SETTLED_TX",
  "timestamp": "2026-09-10T12:00:00.000Z",
  "payerWallet": "0xPAYER",
  "receiverWallet": "0xPAY_TO",
  "network": "eip155:1",
  "asset": "USDC",
  "scheme": "exact",
  "consumerCountry": "DE",
  "consumerName": "Buyer GmbH"
}

curl

export FISCAL402_ORIGIN="https://api.fiscal402.com"
export FISCAL402_API_KEY="$FISCAL402_API_KEY"

curl -sS -X POST "$FISCAL402_ORIGIN/settlements" \
  -H "Content-Type: application/json" \
  -H "X-Fiscal402-Key: $FISCAL402_API_KEY" \
  -H "Idempotency-Key: acme-nl-de-1" \
  -d '{
    "amountUsdc": "1.00",
    "txHash": "0xYOUR_SETTLED_TX",
    "timestamp": "2026-09-10T12:00:00.000Z",
    "payerWallet": "0xPAYER",
    "receiverWallet": "0xPAY_TO",
    "network": "eip155:1",
    "asset": "USDC",
    "scheme": "exact",
    "consumerCountry": "DE",
    "consumerName": "Buyer GmbH"
  }'

201.json

{
  "id": "x402-4f9c1670",
  "custody": "none",
  "reviewStatus": "PROCESSED",
  "classification": {
    "regime": "OSS_B2C",
    "taxCategoryCode": "S",
    "ratePercent": 19,
    "taxingCountry": "DE"
  },
  "fx": {
    "pair": "USDC/EUR",
    "netEur": "0.86",
    "vatEur": "0.16"
  }
}

Errors: 401 AUTHENTICATION_FAILED, 400 BAD_REQUEST, 409 IDEMPOTENCY_CONFLICT, 422 CHAIN_VERIFY_FAILED / UNSUPPORTED_*, 503 DB_UNAVAILABLE.

GET /settlements/:id

Read the fiscal record. GET /settlements/:id/ubl returns the bound XML.

GET /v1/receipts/:id

Fetch fiscal402.receipt/1.0.0. Independent verification uses this JSON plus JWKS, not this origin’s availability. No ingest key.

curl

curl -sS "$FISCAL402_ORIGIN/v1/receipts/rcpt_x402-4f9c1670"
curl -sS "$FISCAL402_ORIGIN/settlements/x402-4f9c1670/ubl" -o invoice.xml
curl -sS "$FISCAL402_ORIGIN/.well-known/jwks.json" -o jwks.json

GET /.well-known/jwks.json

Ed25519 public keys. No authentication.

POST /v1/compliance/evaluate

Sandbox EU VAT classification. Does not write a production settlement. Seller country may be non-EU; the buyer must be an attested EU-27 customer for this preview. Currency is USDC.

POST /v1/capabilities/check

Ask about a corridor before ingest. The response separates event support, payment support, jurisdiction representation, determination coverage, and receipt eligibility. There is no global supported: true for a partially supported corridor.

POST /v1/capabilities/check

POST https://api.fiscal402.com/v1/capabilities/check
Content-Type: application/json

{
  "seller_country": "US",
  "buyer_country": "NL",
  "supply_type": "digital_service",
  "buyer_type": "B2C",
  "payment": {
    "protocol": "x402",
    "network": "eip155:8453",
    "asset": "USDC"
  }
}

POST /v1/fiscal-events

Global FiscalEvent ingest. Authenticated. Accepts ISO 3166-1 parties anywhere. A valid event is persisted even when tax determination is MANUAL_REVIEW_REQUIRED. Production fiscal402.receipt/1.0.0 is issued only when EU VAT production invariants hold. This does not replace POST /settlements.

POST /v1/fiscal-events

POST https://api.fiscal402.com/v1/fiscal-events
Content-Type: application/json
X-Fiscal402-Key: $FISCAL402_API_KEY
Idempotency-Key: acme-us-nl-1

{
  "payment": {
    "amountUsdc": "1.00",
    "txHash": "0xYOUR_SETTLED_TX",
    "timestamp": "2026-09-10T12:00:00.000Z",
    "payerWallet": "0xPAYER",
    "receiverWallet": "0xPAY_TO",
    "network": "eip155:8453",
    "asset": "USDC",
    "scheme": "exact"
  },
  "seller": { "legalName": "Acme Inc", "country": "US" },
  "buyer": { "country": "NL", "businessStatus": "B2C" },
  "supply": { "kind": "digital_service" }
}

Idempotency

Optional header Idempotency-Key. Same key + same body returns the original event. Same key + different body is 409 IDEMPOTENCY_CONFLICT. Duplicate (network, txHash) also returns the existing record.

Identifiers

IdUse
request_idSupport / logs for one HTTP call
event id (x402-…)Fiscal record, UBL, reconciliation
receipt_id (rcpt_…)Portable signed object

Stability

Receipt: fiscal402.receipt/1.0.0 is frozen. Breaking changes get a new spec version and a deprecation period. Webhook payload fields may grow; event type names stay stable.