Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.monkepay.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
onError callback

Register an onError callback to receive SDK errors: 
const monkePay = MonkePayHono({
  apiKeyId: process.env.MONKEPAY_API_KEY_ID!,
  apiKeySecret: process.env.MONKEPAY_API_KEY_SECRET!,
  price: '0.001',
  onError: async (error) => {
    console.error(`[MonkePay] ${error.code}`, {
      phase: error.phase,
      endpoint: error.endpoint,
      recoverable: error.recoverable,
      message: error.message,
      txHash: error.txHash,
    })
    // Send to your alerting system
    await alerts.notify(error)
  },
})
The MonkePayErrorContext object: 
interface MonkePayErrorContext {
  code: MonkePayErrorCode       // error code, see table below
  phase: MonkePayErrorPhase     // where in the lifecycle it happened
  endpoint: string              // request path e.g. '/api/data'
  paymentMode: 'per_request' | 'one_time'
  recoverable: boolean          // true = request continues, false = error sent to agent
  message: string               // human-readable description
  txHash?: string               // settlement tx hash if available
  cause?: unknown               // original error
}

​
Error codes

CodeRecoverableDescription
INVALID_CONFIGNoSDK misconfigured — missing required params. Fix your config and redeploy.
WALLET_RESOLVE_FAILEDYesCould not resolve payout wallet from API credentials. MonkePay API may be temporarily unavailable. Retried automatically on the next request. Agent receives a 502.
UNLOCK_VERIFY_FAILEDYesUnlock token verification failed. Agent falls through to normal payment — they receive a standard 402 and can pay for a new token.
PAYMENT_MIDDLEWARE_FAILEDNox402 payment validation threw unexpectedly. Agent receives a 502.
EVENT_RECORD_FAILEDYesPayment settled on-chain but MonkePay failed to log it. Agent still gets their 200. Revenue is not lost — the on-chain transaction exists.
ON_PAYMENT_CALLBACK_FAILEDYesYour onPayment callback threw an error. Response is unaffected. Fix your callback.
SDK_INTERNAL_ERRORNoUnexpected internal error. Please report this.

​
What agents see

Agents never see internal SDK error details. Error responses are always sanitized: 
{
  "error": {
    "code": "PAYMENT_MIDDLEWARE_FAILED",
    "message": "Payment processing failed"
  }
}
Stack traces and internal details are only available via onError.

​
Express error handler

For Express, register an error handler to catch any errors that reach the end of the middleware chain: 
app.use((err, req, res, next) => {
  console.error(err)
  if (!res.headersSent) {
    res.status(500).json({ error: 'Internal server error' })
  }
})

​
Common issues

Agent receives 402 on every request even after payment
  • Check that your apiKeyId and apiKeySecret are correct
  • Verify your MonkePay account network matches your server network
  • Check onError for WALLET_RESOLVE_FAILED errors
WALLET_RESOLVE_FAILED in onError
  • MonkePay API may be temporarily unavailable
  • Check api.monkepay.xyz/health
  • The error is recoverable — requests will retry wallet resolution automatically
EVENT_RECORD_FAILED in onError
  • Payment happened on-chain and agent received their 200
  • Revenue is safe — the transaction is on-chain
  • The dashboard may not show this payment until the issue is resolved
  • Usually transient — check if it persists