x-api-key header for swap, strategy, wallet, and tracking endpoints.
GET /health is public and does not require authentication. Customer dashboard endpoints (GET /customers/me, /customers/:id/tokens, /customers/:id/token-groups) require a Bearer token (Supabase or Magic JWT) — API key alone is not sufficient because those routes enforce user role checks.Getting an API Key
1
Sign up for Pods
Create an account at pods.finance
2
Navigate to API Keys
Go to the API Keys section in your dashboard
3
Generate New Key
Click “Generate API Key” and give it a descriptive name
4
Copy and Store
Copy your API key immediately - you won’t be able to see it again!
Using Your API Key
Include your API key in thex-api-key header with every request:
Store your API key in a secure server-side environment variable (e.g.
PODS_API_KEY).
Do not expose it in frontend code or commit it to git.API Key Authentication
Recommended for all integrations Use thex-api-key header for all API requests:
- Backend services
- Server-to-server communication
- Automated scripts and bots
- CI/CD pipelines
- All application types
API keys are tied to your customer account and can be rotated or revoked at any time from your dashboard.
Bearer Token Authentication
Required for customer dashboard endpoints Use a Supabase or Magic JWT in theAuthorization header for routes such as GET /customers/me, /customers/:id/tokens, and /customers/:id/token-groups:
admin, owner, developer, viewer). API key authentication alone does not satisfy those checks even when the key is valid.
Supabase sessions require an email confirmed by Supabase Auth. GET /customers/me specifically uses a Supabase token and checks the current Auth user before linking or returning accounts, including internal administrators and existing members. It never creates a new customer organization. Phone verification, browser claims and editable profile metadata do not count as email verification. Google OAuth users qualify when Supabase confirms their email. Users without an existing customer or invitation receive 404 CUSTOMER_NOT_FOUND, even when signup is enabled. Verified invitees activate membership in the existing inviting organization; new-customer provisioning remains in the confirmation webhook.
Administrators and organization owners can still create pending invitation records before verification. These records reserve membership; they do not bypass verified login or account linking. Existing Magic authentication continues to validate its token and obtain the email from the identity provider.
Best for:
- Customer dashboard and admin UI
- Token group and wallet token management
- Profile and account settings (
GET /customers/me)
Rate Limits
API keys are subject to rate limits to ensure fair usage:Rate Limits
- 100 requests per minute per API key
- 1,000 requests per hour per API key
Handling Rate Limits
When you exceed the rate limit, you’ll receive a429 Too Many Requests response:
Retry-After response header contains the delay in seconds.
Security Best Practices
Store Keys Securely
Store Keys Securely
Never hardcode API keys in your source code.Do:
- Use environment variables
- Use secret management services (AWS Secrets Manager, HashiCorp Vault)
- Use encrypted configuration files
- Commit keys to version control
- Include keys in client-side code
- Share keys via email or messaging apps
Rotate Keys Regularly
Rotate Keys Regularly
Rotate your API keys periodically to minimize security risks.Recommended rotation schedule:
- Production keys: Every 90 days
- Development keys: Every 180 days
- Immediately if compromised
- Generate a new API key in your dashboard
- Update your application with the new key
- Test that the new key works
- Delete the old key
Use Different Keys per Environment
Use Different Keys per Environment
Create separate API keys for each environment to isolate security risks.This way, if a development key is compromised, your production environment remains secure.
Monitor API Key Usage
Monitor API Key Usage
Regularly check your API key usage in the dashboard:
- Track request volume
- Monitor for unusual patterns
- Review error rates
- Check which endpoints are being accessed
- Unusually high request volume
- Requests from unexpected IP addresses
- High error rates
Troubleshooting
403 Forbidden
403 Forbidden
Problem: Your request returns a 403 Forbidden error.Possible causes:
- API key doesn’t have permission for this endpoint
- Request from blocked IP address
API Key Not Working
API Key Not Working
Problem: New API key doesn’t work immediately.Solution: API keys may take up to 30 seconds to propagate. Wait a moment and try again.If the issue persists:
- Verify you copied the entire key
- Check for hidden characters or spaces
- Try generating a new key
Next Steps
Quickstart
Make your first API call
API Reference
Explore available endpoints
Yield Guides
Deposit, withdraw, and monitor positions
Swap Guides
Integrate token swaps into your app
New PLG accounts awaiting approval
When self-service signup is enabled, new PLG organizations start with restricted access. Existing customers keep their access. The organization owns the restriction: additional API keys and invited teammates share the same policy. The initial limits are 10 authenticated requests per rolling 60 seconds and $100 of input value per transaction, including swaps, bridges, deposits, withdrawals, transfers, and fiat on/off ramps. These are configurable service defaults, not a cumulative spending budget. A transaction at exactly the USD cap is permitted when its valuation is available. The API uses trusted token metadata and cached prices or FX rates, fetching on cache misses without an additional price-age requirement. It does not trust a client’s USD value, token decimals, or replacement provider payload. Missing, invalid, or unsupported valuation returns503 PLG_VALUATION_UNAVAILABLE. An amount above the cap returns 403 PLG_TRANSACTION_LIMIT_EXCEEDED. A full request window returns 429 RATE_LIMIT_EXCEEDED with the message request limit exceeded and a Retry-After header; an unavailable quota store returns 503 PLG_RATE_LIMIT_UNAVAILABLE.
Restricted customers use the v2 swap API. Legacy /swap/quote and /swap/bytecode, arbitrary user-operation submission, and unbounded whole-position/claim operations require approval (403 PLG_APPROVAL_REQUIRED). The legacy quote endpoint now requires an API key. Quote and bytecode checks apply before admission; they cannot control independent on-chain transactions signed or submitted outside the API. Settlement and refund processing for accepted funds continues under its existing rules.
GET /customers/me includes an access object with approval status, effective limits, and account-block status. Internal administrators can list GET /admin/customers?accessStatus=restricted, inspect GET /admin/customers/{id}, and approve with POST /admin/customers/{id}/approve using x-admin-key. Approval is idempotent and preserves its original timestamp. A shared administrative credential records a service principal, not an individual reviewer’s identity. Approval never clears an account block.
Self-service signup is controlled by PLG_SIGNUP_ENABLED (default true when unset). Set it explicitly to false to close signup. PLG_REQUESTS_PER_MINUTE defaults to 10; PLG_MAX_TRANSACTION_USD defaults to 100. Configure all API replicas consistently. If signup must stay closed during rollout, set PLG_SIGNUP_ENABLED=false explicitly until guards and their dependencies are verified. Closing signup later does not remove restrictions from enrolled accounts.
PLG signup uses ordinary API keys. Provisioning reuses an active key when present or creates one; all keys share the customer-level restrictions. No signup-specific key index migration or legacy-customer backfill is required.