Skip to content

README.md

Latest commit

 

History

History
147 lines (119 loc) · 4.33 KB

README.md

File metadata and controls

147 lines (119 loc) · 4.33 KB
Raw

API Documentation

This directory contains Next.js API routes used by the frontend. Below are the request/response contracts for each endpoint, including their environment variable dependencies.

1. /api/faucet

Mints test USDC to a recipient using the issuer secret.

Method: POST

Environment Variables

  • USDC_ISSUER_SECRET (Required)
  • NEXT_PUBLIC_RPC_URL (Optional, defaults to local RPC)
  • NEXT_PUBLIC_NETWORK_PASSPHRASE (Optional)
  • NEXT_PUBLIC_USDC_CODE (Optional, defaults to USDC)

See the root .env.local or main README for setup instructions on these variables.

Request

{
  "address": "string (Ed25519 public key)",
  "amount": "string | number"
}

Success Response (200 OK)

{
  "hash": "string (transaction hash)",
  "amount": "string (amount minted in 7-decimal stroops)"
}

Error Responses

  • 503 Service Unavailable
    • {"error": "Faucet is not configured (USDC_ISSUER_SECRET unset)."}
  • 429 Too Many Requests
    • {"error": "Too many faucet requests. Try again later."} (Includes Retry-After header)
  • 400 Bad Request
    • {"error": "Invalid request body."}
    • {"error": "Invalid recipient address."}
    • {"error": "Amount must be positive."}
    • {"error": "Faucet simulation failed: <details>"}
  • 500 Internal Server Error
    • {"error": "Faucet transaction submission failed."}
    • {"error": "Faucet transaction did not succeed (<status>)."}
    • {"error": "Faucet failed: <details>"}

2. /api/relay-withdraw

Submits a withdrawal on the user's behalf, paying the transaction fee from the relayer account.

Method: POST

Environment Variables

  • RELAYER_SECRET (Required)
  • NEXT_PUBLIC_RPC_URL (Optional)
  • NEXT_PUBLIC_NETWORK_PASSPHRASE (Optional)

See the root .env.local or main README for setup instructions on these variables.

Request

{
  "poolId": "string (contract ID)",
  "recipient": "string (Ed25519 public key)",
  "publicInputs": "string (hex encoded)",
  "proof": "string (hex encoded)"
}

Success Response (200 OK)

{
  "hash": "string (transaction hash)",
  "relayer": "string (relayer public key)"
}

Error Responses

  • 503 Service Unavailable
    • {"error": "Relayer is not configured (RELAYER_SECRET unset).", "code": "no_relayer"}
  • 429 Too Many Requests
    • {"error": "Too many relay requests. Try again later.", "code": "rate_limited"} (Includes Retry-After header)
  • 400 Bad Request
    • {"error": "Invalid request body."}
    • {"error": "Invalid pool id."}
    • {"error": "Invalid recipient address."}
    • {"error": "publicInputs and proof must be hex strings."}
    • {"error": "Withdrawal simulation failed: <details>"}
  • 500 Internal Server Error
    • {"error": "Relayed withdrawal submission failed."}
    • {"error": "Relayed withdrawal did not succeed (<status>)."}
    • {"error": "Relayed withdrawal failed: <details>"}

3. /api/register-kyc

Registers a KYC hash, granting "compliance-verified" status on the smart contract.

Method: POST

Environment Variables

  • COMPLIANCE_ADMIN_SECRET (Required)
  • NEXT_PUBLIC_COMPLIANCE_CONTRACT_ID (Required)
  • KYC_ADMIN_API_KEY (Required)
  • NEXT_PUBLIC_RPC_URL (Optional)
  • NEXT_PUBLIC_NETWORK_PASSPHRASE (Optional)

See the root .env.local or main README for setup instructions on these variables.

Request Headers

  • x-admin-key: Must match the KYC_ADMIN_API_KEY environment variable.

Request

{
  "kycHash": "string (64 hex characters)"
}

Success Response (200 OK)

{
  "hash": "string (transaction hash)"
}

Error Responses

  • 503 Service Unavailable
    • {"error": "KYC registration is not configured (COMPLIANCE_ADMIN_SECRET unset)."}
    • {"error": "Compliance contract not configured."}
    • {"error": "KYC registration is not configured (KYC_ADMIN_API_KEY unset)."}
  • 401 Unauthorized
    • {"error": "Unauthorized."} (Invalid or missing x-admin-key header)
  • 400 Bad Request
    • {"error": "Invalid request body."}
    • {"error": "kycHash must be exactly 64 hex characters (32 bytes)."}
    • {"error": "Simulation failed: <details>"}
  • 500 Internal Server Error
    • {"error": "KYC registration transaction rejected by the network."}
    • {"error": "KYC registration failed on-chain (<status>)."}
    • {"error": "KYC registration failed: <details>"}