Request x402 payment requirements

Send the final judgement body once to receive the exact network, asset, amount, escrow, and request-scoped authorization to sign.

POST/v1/x402/requests

A 402 response is the expected first step. Takusen returns an x402 v2 PAYMENT-REQUIRED header and the same document as JSON. Keep the serialized request body: the challenge is bound to it and expires after ten minutes.

Parameters

settlementDomainstringbodyrequired

A healthy domainId returned by GET /v1/chain.

promptstringbodyrequired

The complete question, relevant context, and explicit resolution rule.

outputTypeboolean | score | choice | private_hashbodyrequired

The typed result contract used for validation and settlement.

outputSchema{ minimum, maximum, choices[] }bodyrequired

Request-specific bounds and ordered human meanings. Integer ranges must be within 0–100; choices contain 2–26 unique labels and encode as A onward.

modelsstring[]bodyrequired

One or more active model IDs returned by GET /v1/models.

spendLimitMicrosint64bodyrequired

Maximum all-in spend in μUSDC. The payer must already have this amount available in the selected domain.

timeLimitSecondsintbodyrequired

Execution deadline from 5 through 600 seconds.

executionQuorumintbodyrequired

Agreement threshold shown to the consumer; lifecycle finality remains validator-authorized.

visibilitypublicbodyrequired

Use public for sessionless x402 integrations so the result and stream remain readable without application login.

Access

None — this call creates the payment challengeNo application session is required.

Consumer notes

This is prepaid x402: the signature reserves existing domain credits; it does not transfer USDC during each API call.
Fund the payer once before using this flow. The challenge reports the selected USDC asset, escrow, and supported deposit mechanisms.
Smart-contract applications can register extensions.takusen.binding before submitting PAYMENT-SIGNATURE, guaranteeing that binding precedes execution without making result reads private.
Serialize the body once and reuse it for the signed submission. Do not rebuild or mutate it between calls.

curl --request POST \
  --url "$TAKUSEN_API_URL/v1/x402/requests" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --dump-header - \
  --data "$REQUEST_BODY"

402 Payment Required

{
  "x402Version": 2,
  "resource": {
    "url": "https://api.takusen.io/v1/x402/requests",
    "description": "Submit a verifiable AI judgement request"
  },
  "accepts": [
    {
      "scheme": "takusen-prepaid",
      "network": "eip155:84532",
      "amount": "250000",
      "asset": "0x8335...2913",
      "payTo": "0x4f2a...c911",
      "maxTimeoutSeconds": 600
    }
  ],
  "extensions": {
    "takusen": {
      "challengeId": "8fa21e7a-...",
      "mode": "prepaid-escrow",
      "binding": {
        "onchainRequestId": "0x9d8a...31",
        "inputHash": "0xc712...0f",
        "modelSetHash": "0x9211...e801",
        "schemaHash": "0x7712...bf30",
        "settlementDomain": "0x6eb8...44a1",
        "chainId": 84532,
        "onchainModels": [
          {
            "name": "openai/gpt-6-luna",
            "onchainModelId": "0xabcd...1200"
          }
        ],
        "outputSchema": {
          "outputType": 1,
          "minimum": 0,
          "maximum": 1,
          "choicesHash": "0x0000...0000"
        },
        "resultsContract": "0x4f2a...c911",
        "protocolVersion": 2
      },
      "authorization": {
        "primaryType": "AuthorizeRequest",
        "message": {
          "requestId": "0x9d8a...31",
          "inputHash": "0xc712...0f",
          "budget": "250000",
          "deadline": "1983440"
        }
      }
    }
  }
}

Set TAKUSEN_API_URL to the origin of your Takusen API deployment.

On-chain identifiers and result discovery

GET /v1/requests/{id} returns the API UUID together with onchainRequestId, settlementDomain, chainId, escrow, resultsContract, verifier, protocolVersion, modelSetHash, schemaHash, outputSchema, and onchainModels. Every onchainModels entry pairs the public model name with its bytes32 onchainModelId. Integrators do not need to reproduce Takusen's SHA-256 identifier convention before reading ITakusenResults.

GET /v1/chain is the governed deployment registry. The loader requires a non-zero resultsContract and protocolVersion and verifies protocolVersion() against the live contract before exposing a domain; the API returns those verified deployment fields rather than assuming escrow or version 2. Select an active, healthy domain, call its resultsContract through ITakusenResults, wait for FINALIZED unless using a contract-owned irreversible early policy, verify the complete ordered model set, and decode only SUCCESS results with TakusenOutput.