Skip to main content
Pods API uses API keys to authenticate most requests. Include your API key in the 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!
Keep your API keys secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

Using Your API Key

Include your API key in the x-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 the x-api-key header for all API requests:
Best for:
  • 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 the Authorization header for routes such as GET /customers/me, /customers/:id/tokens, and /customers/:id/token-groups:
These routes enforce user role checks (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 a 429 Too Many Requests response:
The Retry-After response header contains the delay in seconds.

Security Best Practices

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
Don’t:
  • Commit keys to version control
  • Include keys in client-side code
  • Share keys via email or messaging apps
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
How to rotate:
  1. Generate a new API key in your dashboard
  2. Update your application with the new key
  3. Test that the new key works
  4. Delete the old key
Create separate API keys for each environment to isolate security risks.
This way, if a development key is compromised, your production environment remains secure.
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
Set up alerts for:
  • Unusually high request volume
  • Requests from unexpected IP addresses
  • High error rates

Troubleshooting

Problem: Your request returns a 401 Unauthorized error.Solutions:
  • Verify your API key is correct
  • Check that the x-api-key header is included
  • Ensure no extra spaces or characters in the key
  • Verify the key hasn’t been deleted or revoked
Problem: Your request returns a 403 Forbidden error.Possible causes:
  • API key doesn’t have permission for this endpoint
  • Request from blocked IP address
Solution: Contact support at [email protected]
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:
  1. Verify you copied the entire key
  2. Check for hidden characters or spaces
  3. 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 returns 503 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.