web/docs/api/examples/secret-system.examples.md

Secret System API Examples (v1)

1) POST /secret/wallet/intent

Request:

{
  "address": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "origin": "https://edut.ai",
  "locale": "en",
  "chain_id": 8453
}

Success (200):

{
  "intent_id": "wi_01HZZX2Q8R0FQFQ6B1VQ1N2P9J",
  "designation_code": "0217073045482",
  "display_token": "0217-0730-4548-2",
  "nonce": "47f43f70d1288d4e",
  "issued_at": "2026-02-17T07:30:45Z",
  "expires_at": "2026-02-17T07:35:45Z",
  "domain_name": "EDUT Designation",
  "chain_id": 8453,
  "verifying_contract": "0x0000000000000000000000000000000000000000"
}

Error (429 rate limited):

{
  "error": "rate_limited",
  "message": "Too many intent requests. Retry later."
}

2) POST /secret/wallet/verify

Request:

{
  "intent_id": "wi_01HZZX2Q8R0FQFQ6B1VQ1N2P9J",
  "address": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "chain_id": 8453,
  "signature": "0xabcdef..."
}

Success (200):

{
  "status": "signature_verified",
  "designation_code": "0217073045482",
  "display_token": "0217-0730-4548-2",
  "verified_at": "2026-02-17T07:31:12Z"
}

Error (400 intent expired):

{
  "error": "intent_expired",
  "message": "Intent has expired. Request a new intent."
}

3) POST /secret/membership/quote

Request:

{
  "designation_code": "0217073045482",
  "address": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "chain_id": 8453
}

Success (200):

{
  "quote_id": "mq_01HZZX4F8VQXJ6A57R8P3SCB2W",
  "chain_id": 8453,
  "currency": "USDC",
  "amount": "5.00",
  "amount_atomic": "5000000",
  "decimals": 6,
  "deadline": "2026-02-17T07:36:12Z",
  "contract_address": "0x1111111111111111111111111111111111111111",
  "method": "mintMembership",
  "calldata": "0xdeadbeef",
  "value": "0x0",
  "tx": {
    "to": "0x1111111111111111111111111111111111111111",
    "data": "0xdeadbeef",
    "value": "0x0"
  }
}

Error (403 not verified):

{
  "error": "signature_not_verified",
  "message": "Signature verification is required before quote issuance."
}

4) POST /secret/membership/confirm

Request:

{
  "designation_code": "0217073045482",
  "quote_id": "mq_01HZZX4F8VQXJ6A57R8P3SCB2W",
  "tx_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "address": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "chain_id": 8453
}

Success (200):

{
  "status": "membership_active",
  "designation_code": "0217073045482",
  "display_token": "0217-0730-4548-2",
  "tx_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "activated_at": "2026-02-17T07:33:09Z"
}

Error (400 tx mismatch):

{
  "error": "tx_mismatch",
  "message": "Transaction amount or destination does not match quote policy."
}

5) GET /secret/membership/status

Request by wallet:

GET /secret/membership/status?wallet=0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5

Success (200):

{
  "status": "active",
  "wallet": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "designation_code": "0217073045482"
}

Error (400 missing selectors):

{
  "error": "missing_selector",
  "message": "Provide wallet or designation_code."
}