Get started - Polygon Developer Docs

OMS gives you a single API for moving money between fiat and stablecoins. This guide takes you from zero to a working transaction in four steps.

Request access and get your API key

OMS is in early access. Start by requesting access from the dashboard.

Request OMS access

Submit your details to get sandbox credentials.

Once approved, open the OMS Dashboard and navigate to API Keys. Generate a new key and store it immediately, it is shown only once.

Treat your API key like a password. If it is ever compromised, revoke it from the dashboard and generate a new one immediately.

All API requests use Bearer authentication:

Authorization: Bearer {your_api_key}

Create a customer

Every wallet, transaction, and payment route in OMS belongs to a customer record. Create one before anything else.

curl -X POST https://sandbox-api.polygon.technology/v0.9/customers \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cst-first-customer-001" \
  -d '{}'

{
  "id": "cst_01H9Xa...",
  "object": "customer",
  "endorsements": [],
  "createdAt": "2024-01-15T10:00:00Z"
}

Store the cst_ ID. The endorsements array starts empty. KYC review grants the endorsements that unlock fiat operations. Your account manager will confirm which endorsement flows apply to your use case.

In sandbox mode all customers are auto-approved with full endorsements so you can test without a KYC integration.

Provision a wallet

Create a custodial wallet for the customer. The customer ID goes in the path, and the body specifies the asset and chain to hold. OMS derives the onchain address and manages the keys, no wallet SDK or user signing required.

curl -X POST https://sandbox-api.polygon.technology/v0.9/customers/cst_01H9Xa.../wallets \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wlt-first-wallet-001" \
  -d '{
    "asset": "usdc",
    "chain": "polygon"
  }'

{
  "id": "wlt_01H9Xb...",
  "object": "wallet",
  "customerId": "cst_01H9Xa...",
  "address": "0xBEEF4a2c891D56e72b67a3f21d0cf94F1D7c5911",
  "asset": "usdc",
  "chain": "polygon",
  "status": "active",
  "createdAt": "2024-01-15T10:01:00Z"
}

The address is the onchain Polygon address. The wlt_ ID is what you pass as source or destination in quotes and transactions.

Run your first transaction

The cash-in flow is available in the OMS API today and is the recommended path for your first run. The bank transfer flow is documented for when external accounts are available to you.

Cash-in
Bank transfer

Let a customer deposit physical cash at a retail location and receive USDC in their wallet.

curl -X POST https://sandbox-api.polygon.technology/v0.9/cash-ins \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-first-001" \
  -d '{
    "customerId": "cst_01H9Xa...",
    "destination": {
      "wallet": { "wallet": "wlt_01H9Xb..." },
      "asset": "usdc",
      "network": "polygon"
    },
    "cash": {
      "cashLocationId": "loc_01H9Xl...",
      "cashLocationReference": "R1JFRU5ET1QtMjQzNDpsYXQ9..."
    },
    "source": { "asset": "usd", "indicatedAmount": "100.00" }
  }'

OMS returns a depositInstructions.code valid for 1 hour. The customer presents the code at the retail location, hands over cash, and USDC lands in their wallet automatically.See the Cash-in guide for the full flow.

Pay out from a wallet to a bank account. Bank rails are in early access; to bring fiat in today, use the Cash-in tab.

Bank payouts are not yet available in the OMS API. The quote below sends USDC from a wallet to a saved bank account (cpUsBank_), which is provisioned through early access. To be notified when it launches, register your interest.

Register interest

Share your use case and we’ll reach out when bank payouts are available.

The quote and transaction calls below are the pattern to use once your external account is provisioned. A quote’s source is always an OMS wallet.Pay out from a wallet to a bank account (USDC to fiat):

# Step 1: create a quote
curl -X POST https://sandbox-api.polygon.technology/v0.9/quotes \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: qt-bank-in-001" \
  -d '{
    "customerId": "cst_01H9Xa...",
    "source": {
      "walletId": "wlt_01H9Xb...",
      "asset": "usdc",
      "network": "polygon",
      "amount": "100.00"
    },
    "destination": {
      "wallet": { "externalAccount": "cpUsBank_01H9Xk..." },
      "asset": "usd",
      "network": "ach"
    }
  }'

# Step 2: execute
curl -X POST https://sandbox-api.polygon.technology/v0.9/transactions \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: txn-bank-in-001" \
  -d '{ "quoteId": "qt_01H9Xq..." }'

See the Bank transfers guide for both directions and ACH-specific flows.

Configure webhooks

OMS fires webhooks at every meaningful state change. You can poll GET /transactions/{id} instead, but webhooks are strongly recommended for production.Configure subscriptions in the OMS Dashboard under Webhooks, or create them via the API with POST /v0.9/webhooks and a url. The signing secret is returned once on creation, so store it immediately. Key events to subscribe to:

Event	When it fires
`transaction.fiatToCrypto.completed`	USDC delivered to wallet
`transaction.cryptoToFiat.completed`	Fiat landed in bank account
`cashIn.completed`	Cash deposit processed
`transaction.*.failed`	Any transaction failure
`customer.endorsement.granted`	KYC approved

Webhook payloads include the full object, so you rarely need to poll for additional data.

Use transaction.*.failed as a catch-all for failure events across all transaction types. The error.code field in the payload tells you what went wrong.

What’s next

Cash-in

Full walkthrough of the cash deposit flow, including deposit code generation and retail location selection.

Bank transfers

Move money between bank accounts and wallets in both directions using ACH and card rails.

Payments overview

How OMS handles payments, stablecoin settlement, and compliant fiat access end to end.

API reference

Complete endpoint reference for all OMS resources.

Request OMS access

Register interest

​What’s next

Cash-in

Bank transfers

Payments overview

API reference

What’s next