​
Overview

API keys are required to authenticate x402 payment verification requests. They provide secure, programmatic access to Meridian’s payment infrastructure for your applications.

​
Key Types

Meridian Protocol uses public keys for API authentication:
  • Public Key (pk_): Used for API authentication
  • Test Mode Keys: Prefixed with pk_test_ for development
  • Production Keys: Prefixed with pk_ for live transactions
Secret keys are generated but only shown once during creation for security. The public key is used for all API requests.

​
Creating API Keys

​
Via Developer Dashboard

1

Sign in with Ethereum

Connect your wallet and authenticate using SIWE
2

Navigate to API Keys

Go to the API Keys section in your developer dashboard
3

Create New Key

Click “Create API Key” and provide a descriptive name
4

Choose Environment

Select test mode for development or production for live transactions
5

Save Your Keys

Copy and securely store both keys - the secret is only shown once!

​
Via API

You can also create API keys programmatically: 
curl -X POST https://api.mrdn.finance/v1/api_keys \
  -H "Content-Type: application/json" \
  -H "Cookie: siwe-session=your_session" \
  -d '{
    "name": "My Application Key",
    "test_net": true
  }'
Response: 
{
  "id": "key_1234567890abcdef",
  "name": "My Application Key",
  "organization": "org_456",
  "api_key": "pk_test_1234567890abcdef...",
  "api_secret_key": "sk_test_abcdef1234567890...",
  "test_net": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}
The api_secret_key is only returned once during creation. Store it securely!

​
Using API Keys

​
Authentication Header

Include your public key in the Authorization header: 
curl -X POST https://api.mrdn.finance/v1/verify \
  -H "Authorization: Bearer pk_1234567890abcdef..." \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": {...},
    "paymentRequirements": {...}
  }'

​
JavaScript/Node.js

const apiKey = 'pk_test_1234567890abcdef...'

const response = await fetch('https://api.mrdn.finance/v1/verify', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    paymentPayload: { /* ... */ },
    paymentRequirements: { /* ... */ }
  })
})

​
Python

import requests

api_key = 'pk_test_1234567890abcdef...'
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.mrdn.finance/v1/verify',
    headers=headers,
    json={
        'paymentPayload': { /* ... */ },
        'paymentRequirements': { /* ... */ }
    }
)

​
Managing API Keys

​
List All Keys

curl https://api.mrdn.finance/v1/api_keys \
  -H "Cookie: siwe-session=your_session"
Response: 
{
  "apiKeys": [
    {
      "id": "key_1234567890abcdef",
      "name": "My Application Key",
      "organization": "org_456",
      "api_key": "pk_test_1234567890abcdef...",
      "test_net": true,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z",
      "last_used_at": "2024-01-01T12:00:00.000Z"
    }
  ]
}

​
Get Single Key

curl https://api.mrdn.finance/v1/api_keys/key_1234567890abcdef \
  -H "Cookie: siwe-session=your_session"

​
Test vs Production Keys

​
Test Mode Keys (pk_test_)

  • Used for development and testing
  • Process payments on testnets (Base Sepolia, etc.)
  • No real money involved
  • Separate analytics and transaction history

​
Production Keys (pk_)

  • Used for live applications
  • Process real payments on mainnets
  • Handle actual value transfers
  • Production-level monitoring and support
Always use test keys during development. Switch to production keys only when your integration is complete and tested.

​
Security Best Practices

​
Key Storage

  • Never commit API keys to version control
  • Use environment variables or secure key management services
  • Rotate keys regularly
  • Use different keys for different environments

​
Access Control

  • API keys are scoped to your organization
  • Each key tracks usage and last access time
  • Keys can be individually managed and revoked

​
Environment Variables

# .env file
MERIDIAN_API_KEY=pk_test_1234567890abcdef...

# In your application
const apiKey = process.env.MERIDIAN_API_KEY

​
API Key Endpoints

Create API Key

POST /v1/api_keys - Create a new API key pair

List API Keys

GET /v1/api_keys - Get all keys for your organization

Get API Key

GET /v1/api_keys/:id - Get details for a specific key

Delete API Key

DELETE /v1/api_keys/:id - Delete an API key

​
Rate Limits

API keys have the following rate limits:
  • Payment Verification: 1,000 requests per hour
  • Transaction Queries: 500 requests per hour
  • API Key Management: 100 requests per hour
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

​
Troubleshooting

​
Common Errors

401 Unauthorized
  • Check that your API key is correct
  • Ensure you’re using the right environment (test vs production)
  • Verify the Authorization header format: Bearer pk_...
403 Forbidden
  • API key may be revoked or expired
  • Check if you’re accessing the correct organization’s resources
429 Rate Limited
  • You’ve exceeded the rate limit for your API key
  • Wait for the reset time or contact support for higher limits

​
Testing Your API Key

# Test authentication
curl https://api.mrdn.finance/v1/supported \
  -H "Authorization: Bearer pk_test_your_key_here"

# Should return supported payment kinds
{
  "kinds": [
    {
      "x402Version": 1,
      "scheme": "exact", 
      "network": "base-sepolia"
    }
  ]
}

​
Next Steps

Verify Payments

Start verifying x402 payments with your API key

View Transactions

Monitor your payment transactions

Get Analytics

Access detailed payment analytics

Developer Dashboard

Manage keys in the web interface