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.

​
Required

​
apiKeyId

Type: string Your MonkePay API key ID. Get this from the dashboard under API Keys. 
apiKeyId: process.env.MONKEPAY_API_KEY_ID!

​
apiKeySecret

Type: string Your MonkePay API key secret. Used to sign requests to the MonkePay API. Never log or commit this. 
apiKeySecret: process.env.MONKEPAY_API_KEY_SECRET!

​
price

Type: string Price per request in USDC. The $ prefix is optional. 
price: '0.001'   // $0.001 USDC
price: '$0.10'   // $0.10 USDC — both forms are equivalent
Minimum: 0.000001 (1 atomic USDC unit). Maximum: 1000000.

​
Optional

​
paymentMode

Type: 'per_request' | 'one_time' Default: 'per_request' Controls how agents are charged. See Payment Modes for full details.
  • per_request — every request requires payment
  • one_time — agent pays once, receives an unlock token granting permanent access to that endpoint
paymentMode: 'one_time'

​
unlockHeaderName

Type: string Default: 'X-MonkePay-Unlock' The header name used to pass the one-time unlock token. Only relevant when paymentMode is 'one_time'. Change this if the default conflicts with your existing headers. 
unlockHeaderName: 'X-My-Unlock-Token'

​
baseUrl

Type: string Your API’s public base URL. Required for Fastify when running behind a reverse proxy (Railway, Render, Fly, etc). Without it, x402 may construct http:// resource URLs when your API is actually https://. 
baseUrl: 'https://api.yourcompany.com'
See Reverse Proxies for details.

​
onPayment

Type: (event: PaymentEvent) => void | Promise<void> Callback fired after every successful payment settlement. Use it for usage tracking, webhooks, or business logic. 
onPayment: async (payment) => {
  console.log(`${payment.agentAddress} paid ${payment.amountUSDC} USDC`)
  await db.insert({ ...payment })
}
onPayment errors are caught and logged — they never interrupt the response or surface to the agent. See onPayment Callback for full details.

​
onError

Type: (error: MonkePayErrorContext) => void | Promise<void> Callback fired on internal SDK errors. Use it to pipe errors to your alerting or logging system. 
onError: async (error) => {
  await alerting.notify({
    code: error.code,
    phase: error.phase,
    recoverable: error.recoverable,
    message: error.message,
  })
}
See Error Handling for full details including error codes.

​
Per-route overrides

All adapters support per-route overrides. Set defaults at the instance level and override per route. Any config option can be overridden except apiKeyId and apiKeySecret. 
const monkePay = MonkePayHono({
  apiKeyId: process.env.MONKEPAY_API_KEY_ID!,
  apiKeySecret: process.env.MONKEPAY_API_KEY_SECRET!,
  price: '0.001', // default
})

app.use('/api/cheap', monkePay({ price: '0.001' }))
app.use('/api/expensive', monkePay({ price: '0.10' }))
app.use('/api/report', monkePay({ price: '1.00', paymentMode: 'one_time' }))
See Per-route Pricing for adapter-specific examples.

​
Full example

const monkePay = MonkePayHono({
  apiKeyId: process.env.MONKEPAY_API_KEY_ID!,
  apiKeySecret: process.env.MONKEPAY_API_KEY_SECRET!,
  price: '0.001',
  paymentMode: 'per_request',
  baseUrl: 'https://api.yourcompany.com',
  onPayment: async (payment) => {
    console.log('Payment received:', payment)
  },
  onError: async (error) => {
    console.error('SDK error:', error.code, error.message)
  },
})