HTTP API - Subscribtion Payment#

Subscription Model Overview#

Subscription payments are built on an on-chain subscription contract (Permit2 AllowanceTransfer authorization model), enabling "sign once, pull payment every billing period":

• Buyer (payer) signs two objects off-chain: SubscriptionTerms (the subscription terms) + a Permit2 PermitSingle (allowance authorization). No further signature is needed for each period's payment;

• Seller (merchant) backend collects the Buyer's two signatures, calls the Broker API to create the subscription, and initiates a charge after each billing period becomes due (Seller-Driven);

• Broker (facilitator) verifies the signatures and terms, then submits the on-chain transaction on behalf of the parties. terms.facilitator must equal the facilitator address returned by /supported.

• Base URL: https://web3.okx.com

• Path prefix: /api/v6/pay/x402

• Network: X Layer (chainId 196, CAIP-2 identifier eip155:196)

Authentication#

Endpoints fall into two authentication tiers:

• API Key authentication: all write endpoints (create / charge / change / cancel / cancel-pending-change / finalize-expired) plus the two merchant-facing queries charges and pending. Requests carry the OK-ACCESS-* headers. The merchant identity behind the API Key is also the authorization baseline: it is persisted when the subscription is created, and subsequent charge / change / merchant-initiated cancel calls must come from the same merchant.

• Public read-only: /supported, subscriptions/detail, and buyers/{buyer}/* require no API Key (everything they return is derivable from on-chain data) and can be called directly by the Buyer; rate limits still apply.

All responses use a unified business envelope:

{
  "code": "0",
  "msg": "",
  "data": { /* business fields */ }
}

On business errors, code is non-"0", data is null, and msg carries a machine-readable error identifier (e.g. period_not_due). See the Error Codes section at the end.

Common Conventions#

syncSettle (all write endpoints)#

Every write endpoint body supports the syncSettle field:

• true: block and poll until the on-chain terminal state or a timeout (default 5000ms); the returned data reflects the latest persisted state;

• false / omitted: return immediately after submission (state is usually pending); poll the query endpoints afterwards.

Field Representation#

• Amounts (amountPerPeriod / initialChargeAmount / amount): decimal strings in atomic units;

• Times (periodSec / startAt / termsDeadline / expiration / deadline): Unix seconds;

• subId / salt / nonce / permitHash / changeFromSubId: bytes32 as 0x + 64 hex chars;

• Addresses: 0x + 40 hex chars, lowercase.

Enums#

Period Mode (periodMode)#

Key calendar-month semantics:

• The anchor never drifts: every boundary is computed by adding n months to the original anchor billingAnchorAt, e.g. 1/31 12:00 → 2/28 → 3/31 → 4/30; it does not chain-drift onto a day-28 rhythm;

• The exact boundary instant belongs to the next period;

• billingAnchorAt: for a plain new subscription it equals startAt; upgrades / downgrade activation inherit the old subscription's anchor (the month-end rhythm continues); when startAt=0 it is backfilled from the chain;

• All timestamps are UTC;

• Skipped periods are never back-charged: missed intermediate periods release their reserved allowance; a charge only pulls the current period (identical semantics in both modes).

1. /api/v6/pay/x402/supported#

Queries the schemes, networks, and signer list supported by the Broker (no API Key required). Call this endpoint before subscription integration to obtain the subscription contract address and facilitator address.

Subscription capability is advertised as entries with scheme="period" in the kinds array (emitted dynamically based on rollout switches and per-chain contract configuration):

signers[network] lists all available facilitator EOAs on that chain, so Sellers can verify that a given address belongs to this facilitator.

Request Example#

curl --location --request GET 'https://web3.okx.com/api/v6/pay/x402/supported'

Response Example#

{
  "code": "0",
  "msg": "",
  "data": {
    "kinds": [
      { "x402Version": 2, "scheme": "exact",         "network": "eip155:196" },
      { "x402Version": 2, "scheme": "aggr_deferred", "network": "eip155:196" },
      {
        "x402Version": 2,
        "scheme": "period",
        "network": "eip155:196",
        "extra": {
          "facilitatorAddress": "0xFacilitatorEOA...",
          "subscriptionContract": "0xSubscriptionContract...",
          "permit2Contract": "0x000000000022d473030f116ddee9f6b43ac78ba3"
        }
      }
    ],
    "extensions": [],
    "signers": {
      "eip155:196": [
        "0xFacilitatorEOA...",
        "0xFacilitatorEOA2..."
      ]
    }
  }
}

2. /api/v6/pay/x402/subscriptions#

Creates a subscription. The Buyer's two signatures (SubscriptionTerms + Permit2 PermitSingle) are forwarded and submitted by the Seller backend; the contract creates the subscription and charges the initial amount per the initial-charge parameters.

Request Parameters#

Constraints:

• On create, terms.changeFromSubId must be all zeros and terms.changeEffectiveAt must be 0;

• Initial-charge rules: when initialChargePeriods > 0, initialChargeAmount ≤ initialChargePeriods × amountPerPeriod is required; initialChargePeriods = 0 with initialChargeAmount > 0 is a pre-start upfront fee (must be ≤ amountPerPeriod and requires startAt > now);

• The permit allowance must cover the subscription's full commitment, and permit.details.expiration must not be earlier than the end of the subscription's service window;

• Creation moves funds, so compliance screening runs on both payer and merchant; blocklisted addresses are rejected.

Response Parameters#

Request Example (calendar-month billing)#

curl --location --request POST 'https://web3.okx.com/api/v6/pay/x402/subscriptions' \
--header 'Content-Type: application/json' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2026-04-01T12:21:41.274Z' \
--data '{
  "chainIndex": 196,
  "terms": {
    "payer": "0x1111111111111111111111111111111111111111",
    "merchant": "0x2222222222222222222222222222222222222222",
    "facilitator": "0xFacilitatorEOA...",
    "token": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
    "amountPerPeriod": "5000000",
    "periodSec": 0,
    "maxPeriods": 12,
    "startAt": 0,
    "initialChargePeriods": 1,
    "initialChargeAmount": "5000000",
    "termsDeadline": 1781000000,
    "permitHash": "0xab12...permitStructHash...cd34",
    "salt": "0x7f3a...random32bytes...9e01",
    "planId": "0x0000...keccak(pro_monthly)...0000",
    "planTier": 2,
    "changeFromSubId": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "changeEffectiveAt": 0,
    "periodMode": 1
  },
  "permit": {
    "details": {
      "token": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
      "amount": "60000000",
      "expiration": 1812600000,
      "nonce": 5
    },
    "spender": "0xSubscriptionContract...",
    "sigDeadline": "1781000600"
  },
  "termsSig": "0x<65-byte hex>",
  "permitSig": "0x<65-byte hex>",
  "syncSettle": true
}'

Fixed-seconds mode: set periodMode=0 and a positive periodSec (e.g. 2592000 for monthly).

Response Example#

{
  "code": "0",
  "msg": "",
  "data": {
    "subId": "0x9a8b...termsDigest...c7d6",
    "txHash": "0xabc...create...def",
    "state": 1
  }
}

3. /api/v6/pay/x402/subscriptions/charge#

Periodic charge. Initiated by the Seller backend once the billing period is due; no further Buyer signature is required. Only the merchant (API Key) that created the subscription may call it.

Request Parameters#

Validation chain: the subscription must be active; not all periods charged yet (otherwise all_periods_charged); the current period must be due (otherwise period_not_due); when due, compliance screening runs on payer and merchant.

Response Parameters#

Request Example#

curl --location --request POST 'https://web3.okx.com/api/v6/pay/x402/subscriptions/charge' \
--header 'Content-Type: application/json' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2026-04-01T12:21:41.274Z' \
--data '{ "subId": "0x9a8b...c7d6", "syncSettle": true }'

Response Example — Regular Charge#

{
  "code": "0",
  "msg": "",
  "data": {
    "subId": "0x9a8b...c7d6",
    "period": 4,
    "txHash": "0xabc...charge...def",
    "state": 1,
    "planChangeTriggered": false,
    "newSubId": null
  }
}

Response Example — Downgrade Switch Triggered This Period#

{
  "code": "0",
  "msg": "",
  "data": {
    "subId": "0x9a8b...c7d6",
    "period": 4,
    "txHash": "0xabc...activate...def",
    "state": 1,
    "planChangeTriggered": true,
    "newSubId": "0x2c1d...newDowngradeSubId...8f0a"
  }
}

4. /api/v6/pay/x402/subscriptions/change#

Plan upgrade / downgrade. An upgrade (changeEffectiveAt=1) takes effect immediately and charges the new tier's first period; a downgrade (changeEffectiveAt=2) is scheduled to the end of the current period and is switched by the next charge. Only the merchant that created the subscription may call it.

Request Parameters#

Direction rules and constraints:

• newTerms.planTier > old planTier requires changeEffectiveAt=1 (upgrade); < requires changeEffectiveAt=2 (downgrade); equal tiers are rejected (tier_same);

• The following must be identical across old and new subscriptions: payer / merchant / facilitator / token / periodSec / periodMode (the period mode cannot be switched);

• The old subscription must be active with no scheduled-but-not-yet-effective downgrade (otherwise pending_change_exists);

• For downgrades, newTerms.initialChargeAmount must be 0;

• newTerms.startAt rules: if the old subscription has not started yet (pre-start), it must equal the old subscription's startAt; for downgrades and for in-effect upgrades in fixed mode it must be 0; for in-effect calendar-month upgrades it may equal the start of the old subscription's current period (aligned upgrade — inherits the old anchor; period 1 retroactively covers the old current period and is charged in full) or 0 (re-anchor from the transaction time).

Response Parameters#

Request Example — Upgrade (immediate)#

curl --location --request POST 'https://web3.okx.com/api/v6/pay/x402/subscriptions/change' \
--header 'Content-Type: application/json' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2026-04-01T12:21:41.274Z' \
--data '{
  "chainIndex": 196,
  "oldSubId": "0x9a8b...c7d6",
  "newTerms": {
    "payer": "0x1111111111111111111111111111111111111111",
    "merchant": "0x2222222222222222222222222222222222222222",
    "facilitator": "0xFacilitatorEOA...",
    "token": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
    "amountPerPeriod": "20000000",
    "periodSec": 0,
    "maxPeriods": 12,
    "startAt": 0,
    "initialChargePeriods": 0,
    "initialChargeAmount": "0",
    "termsDeadline": 1781200000,
    "permitHash": "0x<new permit struct hash>",
    "salt": "0x<new random32bytes>",
    "planId": "0x<keccak(enterprise_monthly)>",
    "planTier": 3,
    "changeFromSubId": "0x9a8b...c7d6",
    "changeEffectiveAt": 1,
    "periodMode": 1
  },
  "permit": {
    "details": { "token": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8", "amount": "240000000", "expiration": 1812600000, "nonce": 6 },
    "spender": "0xSubscriptionContract...",
    "sigDeadline": "1781200600"
  },
  "termsSig": "0x<65-byte hex>",
  "permitSig": "0x<65-byte hex>",
  "syncSettle": true
}'

Response Example — Upgrade#

{
  "code": "0",
  "msg": "",
  "data": { "newSubId": "0x6b5c...upgradedSubId...a1f2", "txHash": "0xabc...upgrade...def", "state": 1 }
}

Response Example — Downgrade (scheduled to period end)#

Request-body differences: newTerms.changeEffectiveAt=2, a lower planTier, startAt=0, initialChargeAmount="0".

{
  "code": "0",
  "msg": "",
  "data": { "newSubId": "0x2c1d...pendingNewSubId...8f0a", "txHash": "0xabc...schedule...def", "state": 1 }
}

The downgrade response's state is the old subscription's state (still 1 active); newSubId is the pending new subId, which only takes effect after the next charge triggers activation.

5. /api/v6/pay/x402/subscriptions/cancel#

Cancels a subscription. Requires an off-chain CancelAuth signature (either payer or merchant can initiate). After cancellation, future charges stop and the reserved allowance is released.

Request Parameters#

Validation: the subscription must be active; cancelAuth.subId = body subId; deadline > now; the recovered signer = payer (initiator=0) or merchant (initiator=1); for initiator=1 the caller's API Key must also be the subscription's creating merchant.

Response Parameters#

Request Example#

curl --location --request POST 'https://web3.okx.com/api/v6/pay/x402/subscriptions/cancel' \
--header 'Content-Type: application/json' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2026-04-01T12:21:41.274Z' \
--data '{
  "subId": "0x9a8b...c7d6",
  "cancelAuth": {
    "action": 0,
    "initiator": 0,
    "subId": "0x9a8b...c7d6",
    "nonce": "0x<random32bytes>",
    "deadline": 1781300000,
    "signature": "0x<65-byte hex, signed by payer>"
  },
  "syncSettle": true
}'

Response Example#

{
  "code": "0",
  "msg": "",
  "data": { "subId": "0x9a8b...c7d6", "txHash": null, "state": 3 }
}

6. /api/v6/pay/x402/subscriptions/cancel-pending-change#

Cancels a scheduled but not-yet-effective downgrade. Only the payer can sign the authorization.

Request Parameters#

Validation: a downgrade schedule in pending state must exist (otherwise no_pending_change_or_not_pending); cancelAuth.subId = the schedule's subId; cancelAuth.newSubId = the schedule's newSubId (otherwise pending_cancel_target_mismatch); deadline > now; the recovered signer = the subscription's payer.

newSubId can be obtained from the pendingPlanChange.newSubId field of the subscription detail response.

Response Parameters#

Request Example#

curl --location --request POST 'https://web3.okx.com/api/v6/pay/x402/subscriptions/cancel-pending-change' \
--header 'Content-Type: application/json' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2026-04-01T12:21:41.274Z' \
--data '{
  "subId": "0x9a8b...c7d6",
  "cancelAuth": {
    "subId": "0x9a8b...c7d6",
    "newSubId": "0x2c1d...pendingNewSubId...8f0a",
    "nonce": "0x<random32bytes>",
    "deadline": 1781300000,
    "signature": "0x<65-byte hex, signed by payer only>"
  },
  "syncSettle": true
}'

Response Example#

{
  "code": "0",
  "msg": "",
  "data": { "subId": "0x9a8b...c7d6", "txHash": "0xabc...schedule...def", "state": 2 }
}

7. /api/v6/pay/x402/subscriptions/finalize-expired#

Finalizes a subscription whose service window has ended but which was never terminated, releasing its reserved allowance in the subscription contract so the Buyer can use it for a new subscription.

Request Parameters#

Validation: the subscription is active and its service window has ended (fixed mode: now ≥ startAt + maxPeriods × periodSec; calendar month: now ≥ addMonths(anchor, maxPeriods); otherwise not_ended).

Response Parameters#

Request Example#

curl --location --request POST 'https://web3.okx.com/api/v6/pay/x402/subscriptions/finalize-expired' \
--header 'Content-Type: application/json' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2026-04-01T12:21:41.274Z' \
--data '{ "subId": "0x9a8b...c7d6" }'

Response Example#

{
  "code": "0",
  "msg": "",
  "data": { "subId": "0x9a8b...c7d6", "txHash": null, "state": null }
}

8. /api/v6/pay/x402/subscriptions/detail#

Queries subscription details (public read-only, no API Key). The Buyer can call it directly — for example to read pendingPlanChange.newSubId when signing a cancel-pending-change authorization.

Request Parameters#

Response Parameters#

Request Example#

curl --location --request GET 'https://web3.okx.com/api/v6/pay/x402/subscriptions/detail?subId=0x9a8b...c7d6'

Response Example#

{
  "code": "0",
  "msg": "",
  "data": {
    "subId": "0x9a8b...c7d6",
    "state": 1,
    "payer": "0x1111111111111111111111111111111111111111",
    "merchant": "0x2222222222222222222222222222222222222222",
    "token": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
    "amountPerPeriod": "20000000",
    "periodSec": 0,
    "periodMode": 1,
    "maxPeriods": 12,
    "startAt": 1781001000,
    "billingAnchorAt": 1781001000,
    "lastChargedPeriod": 3,
    "totalPulled": "60000000",
    "planId": "0x<keccak(pro_monthly)>",
    "planTier": 2,
    "changedToSubId": null,
    "isActive": true,
    "serviceEnded": false,
    "currentPeriod": 4,
    "elapsedPeriods": 4,
    "nextChargeableAt": 1788777000,
    "pendingPlanChange": {
      "subId": "0x9a8b...c7d6",
      "newSubId": "0x2c1d...pendingNewSubId...8f0a",
      "effectiveFromPeriod": 5,
      "state": 0
    }
  }
}

9. /api/v6/pay/x402/subscriptions/charges#

Queries a subscription's charge records (merchant endpoint, API Key required).

Request Parameters#

Response Parameters#

charges array, each item:

Request Example#

curl --location --request GET 'https://web3.okx.com/api/v6/pay/x402/subscriptions/charges?subId=0x9a8b...c7d6&limit=50&offset=0' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2026-04-01T12:21:41.274Z'

Response Example#

{
  "code": "0",
  "msg": "",
  "data": {
    "charges": [
      { "subId": "0x9a8b...c7d6", "period": 3, "chargeType": 2, "amount": "20000000", "state": 1, "txHash": "0x...p3...", "planChangeTriggered": false, "newSubId": null },
      { "subId": "0x9a8b...c7d6", "period": 1, "chargeType": 1, "amount": "20000000", "state": 1, "txHash": "0x...init...", "planChangeTriggered": false, "newSubId": null }
    ]
  }
}

10. /api/v6/pay/x402/subscriptions/pending#

Queries the subscription's most recent downgrade schedule record (any state, so terminal states canceled / activated / expired are observable; merchant endpoint, API Key required). All fields are null when no record exists.

Request Parameters#

Response Parameters#

Request Example#

curl --location --request GET 'https://web3.okx.com/api/v6/pay/x402/subscriptions/pending?subId=0x9a8b...c7d6' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2026-04-01T12:21:41.274Z'

Response Example — Schedule Exists#

{
  "code": "0",
  "msg": "",
  "data": { "subId": "0x9a8b...c7d6", "newSubId": "0x2c1d...8f0a", "effectiveFromPeriod": 5, "state": 0 }
}

Response Example — No Schedule#

{
  "code": "0",
  "msg": "",
  "data": { "subId": null, "newSubId": null, "effectiveFromPeriod": null, "state": null }
}

11. /api/v6/pay/x402/buyers/{buyer}/allowance-status#

Queries the Buyer's two-layer allowance status (public read-only, no API Key). The Buyer SDK uses it to build the PermitSingle and to decide whether an ERC-20 approve is needed first. Results are not cached (in-flight transactions may change the nonce).

Request Parameters#

Response Parameters#

Request Example#

curl --location --request GET 'https://web3.okx.com/api/v6/pay/x402/buyers/0x1111111111111111111111111111111111111111/allowance-status?token=0x4ae46a509f6b1d9056937ba4500cb143933d2dc8&chainIndex=196'

Response Example#

{
  "code": "0",
  "msg": "",
  "data": {
    "approvedAmount": "100000000",
    "expiration": 1812600000,
    "nonce": 5,
    "reservedAmount": "40000000",
    "reservedExpiration": 1812600000,
    "tokenBalance": "523000000",
    "availableAmount": "60000000",
    "permit2Allowance": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
    "subscriptionContract": "0xSubscriptionContract...",
    "permit2Contract": "0x000000000022d473030f116ddee9f6b43ac78ba3"
  }
}

12. /api/v6/pay/x402/buyers/{buyer}/subscriptions#

Queries the Buyer's own subscription list (public read-only, no API Key). No merchant identity information is returned (no merchant / facilitator / subscriptionContract).

Request Parameters#

Response Parameters#

subscriptions array, each item:

Request Example#

curl --location --request GET 'https://web3.okx.com/api/v6/pay/x402/buyers/0x1111111111111111111111111111111111111111/subscriptions?limit=20&offset=0'

Response Example#

{
  "code": "0",
  "msg": "",
  "data": {
    "subscriptions": [
      {
        "chainIndex": 196,
        "subId": "0x9a8b...c7d6",
        "state": 1,
        "payer": "0x1111111111111111111111111111111111111111",
        "token": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
        "amountPerPeriod": "20000000",
        "periodSec": 0,
        "periodMode": 1,
        "maxPeriods": 12,
        "startAt": 1781001000,
        "billingAnchorAt": 1781001000,
        "initialChargePeriods": 0,
        "initialChargeAmount": "0",
        "lastChargedPeriod": 3,
        "totalPulled": "60000000",
        "planId": "0x<keccak(pro_monthly)>",
        "planTier": 2,
        "changedToSubId": null,
        "isActive": true,
        "serviceEnded": false,
        "currentPeriod": 4,
        "elapsedPeriods": 4,
        "nextChargeableAt": 1788777000
      }
    ]
  }
}

Common Data Structures#

SubscriptionTerms#

The subscription terms signed by the Buyer — 17 fields, all included in the EIP-712 signature (except planId). subId = the EIP-712 digest of the terms.

PermitSingle#

Permit2 AllowanceTransfer authorization object.

CancelAuth#

Subscription cancellation authorization (signed by payer or merchant).

PendingChangeCancelAuth#

Authorization to cancel a scheduled downgrade (signed by the payer only).

EIP-712 Signature Definitions#

Domain (domain separator)#

Final digest: keccak256(0x1901 ‖ domainSeparator ‖ structHash).

TypeString#

SubscriptionTerms(address payer,address merchant,address facilitator,address token,uint160 amountPerPeriod,uint64 periodSec,uint32 maxPeriods,uint64 startAt,uint32 initialChargePeriods,uint160 initialChargeAmount,uint64 termsDeadline,bytes32 permitHash,bytes32 salt,uint8 planTier,bytes32 changeFromSubId,uint8 changeEffectiveAt,uint8 periodMode)
CancelAuth(uint8 action,bytes32 subId,uint8 initiator,bytes32 nonce,uint64 deadline)
PendingChangeCancelAuth(bytes32 subId,bytes32 newSubId,bytes32 nonce,uint64 deadline)
PermitSingle(PermitDetails details,address spender,uint256 sigDeadline)PermitDetails(address token,uint160 amount,uint48 expiration,uint48 nonce)

Signature requirements:

• All signatures are 65-byte secp256k1 (r‖s‖v) with EIP-2 low-s enforced (s ≤ N/2, otherwise rejected with signature_high_s);

• Before signing, you can eth_call the subscription contract's hashSubscriptionTerms(terms) / hashPermitSingle(permit) view functions to cross-check your locally computed digests;

• Permit2 on-chain prerequisite: the Buyer must first grant a sufficient approve to the Permit2 canonical contract 0x000000000022d473030f116ddee9f6b43ac78ba3, otherwise creation is rejected.

Supported Networks and Tokens#

Stablecoins supported on X Layer:

Error Codes#

Error responses use the unified envelope {"code": "<code>", "msg": "<message>", "data": null}.

1. Authentication Errors (HTTP 401)#

2. Request Errors#

3. Business Errors#

Business errors on subscription endpoints return HTTP 200, with code set to the business error code and msg carrying a machine-readable error identifier (some append : plus a human-readable note):

4. msg Error Identifiers#

Common values (grouped by triggering endpoint):

General

Create / Change (terms and signature validation)

Change-specific

Charge

Cancel / Cancel-pending-change / Finalize

On-chain