Sign in
Payments

Create an email-native payment challenge

Changed on

Issue an x402 payment challenge over a real email thread (the payee side). Unlike createChallenge (which mints a synthetic challenge id), this sends the challenge as an email from from to to and binds the payment to that DKIM-authenticated thread. The pay_to address and the token asset are resolved server-side from your registered default payout address for the network, never from the request. The response carries the thread's interaction_id plus the challenge (the payment_requirements, the nonce_binding, and expires_at) the payer needs to sign; the payer replies with a signed payment interaction step. Amounts are in token base units (USDC has 6 decimals, so "10000" is 0.01 USDC).

post/x402/email-challenges

Request

  • Base URL: https://api.primitive.dev/v1
  • URL: https://api.primitive.dev/v1/x402/email-challenges
  • Auth: HTTP bearer

Headers

idempotency-keystring

Optional idempotency key. Retrying a request with the same key returns the original result instead of repeating the side effect (for createEmailChallenge, re-sending the email).

Request body

fromstring email required

Your sending address (the payee / funds receiver). Must be an address your org is allowed to send from.

tostring email required

The payer's email address the challenge is sent to.

amountstring required

Amount to collect, in token base units (unlike the charge CLI command, which also accepts --amount-usdc, this field takes base units only). USDC has 6 decimals, so "10000" is 0.01 USDC: multiply a human USDC amount by 1,000,000 (0.01 USDC -> "10000").

network'base' | 'base-sepolia' required
expires_ininteger

Seconds until the challenge expires. Defaults to 300.

resourcestring uri

Optional URL identifying what is being paid for.

descriptionstring

Optional human-readable description of the payment.

Response

Idempotent replay: a request with a previously-used idempotency key returns the original issued challenge without sending a second email.

successboolean required

Example response

{
  "data": {
    "challenge": {
      "payment_requirements": {
        "scheme": "exact"
      }
    }
  }
}

Changes

  • 52138fa51360Revision changes
    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

  • 22d1dfc68434Revision changes
    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status