Get started

In this tutorial you will use the OMS sandbox to take one customer from nothing to a funded wallet. You will authenticate, create a customer, give them a USDC wallet on Polygon, fund it with a simulated cash deposit, and watch the resulting transaction complete. Every request runs against https://sandbox-api.polygon.technology/v0.13, so no real money moves. You need curl and sandbox API credentials. The same requests work in production against https://api.polygon.technology/v0.13 with production credentials.

Get sandbox credentials

OMS is in early access. Request access to receive sandbox credentials.

Request OMS access

Submit your details to get sandbox credentials.

Once approved, open the OMS Dashboard and go to API Keys. Generate a secret key and copy both the key (it starts with sk_sdbx_) and its secret. The secret is shown only once.

Treat your API secret like a password and keep it on your server. If it is ever exposed, revoke the key in the dashboard and generate a new one.

Exchange your key for a bearer token

You never send the API key on ordinary requests. Exchange the key and secret for a bearer token:

curl -X POST https://sandbox-api.polygon.technology/v0.13/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "{api_key}",
    "apiSecret": "{api_secret}"
  }'

{
  "accessToken": "eyJhbGc...",
  "tokenType": "bearer",
  "expiresIn": 3600,
  "expiresAt": "2026-11-02T11:00:00.000Z",
  "projectId": "{project_id}",
  "projectMode": "sandbox"
}

Notice that projectMode is sandbox. The token is valid for 60 minutes. Send it on every other request in this tutorial:

Authorization: Bearer {accessToken}

Every other POST in this tutorial also needs an Idempotency-Key header. Use a new UUID for each new request, and send the same key again only to retry that exact request.

If a later request returns 401, your token has expired. Run this step again and continue. If POST /auth/token returns 429, wait for the number of seconds in the Retry-After header.

Create a customer

Every wallet, quote, and transaction belongs to a customer. Create an individual customer with the identifying details OMS needs to provision a wallet and accept cash:

curl -X POST https://sandbox-api.polygon.technology/v0.13/customers \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{
    "type": "individual",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com",
    "phone": "+14155550123",
    "birthDate": "1990-05-15",
    "nationality": "US",
    "residentialAddress": {
      "line1": "100 Market St",
      "city": "San Francisco",
      "state": "CA",
      "zipCode": "94105",
      "country": "US"
    },
    "identifyingInformation": [
      { "type": "ssn", "issuingCountry": "US", "number": "{ssn}" }
    ]
  }'

You get back the customer with 201:

{
  "id": "cst_01H9Xa...",
  "type": "individual",
  "name": "Jane Smith",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "nationality": "US",
  "status": "active",
  "signedAgreement": false,
  "endorsements": [
    { "type": "basic", "status": "active" },
    { "type": "cryptoCustody", "status": "active" },
    { "type": "usd", "status": "active" }
  ],
  "createdAt": "2026-11-02T10:00:00.000Z",
  "updatedAt": "2026-11-02T10:00:00.000Z"
}

Copy the cst_ ID; you use it in every remaining step. The birthDate, residentialAddress, and identifyingInformation you sent are write-only, so they never appear in responses. Sandbox runs the same onboarding checks as production, so wait until the customer’s status is active before you continue (poll GET /customers/{customerId} or listen for the customer.* webhooks). See Sandbox and testing if a check rejects your data.If the response is 202 with "status": "processing" instead, onboarding is still running. Wait a few seconds, then send the identical request with the same Idempotency-Key. You get 202 again while it runs and 201 with the customer once it is done.

Use these fields exactly as shown. Projects that require identity verification for custodial wallets need email, birthDate as YYYY-MM-DD, a US phone in E.164 format (+1 and 10 digits), an ssn entry in identifyingInformation, and a US residentialAddress with a two-letter state. Addresses in New York, Texas, and Vermont are not supported on these projects. Avoid the word “test” in names and emails, which can trip fraud checks.

If the request fails with 400, read the cause field in the error body for the specific reason, and quote the response’s Request-Id header if you contact support. Fields the API does not recognize are ignored rather than rejected, so check spelling carefully. For business customers and the full onboarding lifecycle, see Customer onboarding.

Create a USDC wallet

Give the customer a custodial wallet that holds USDC on Polygon. OMS manages the keys, so there is nothing for the customer to sign.

curl -X POST https://sandbox-api.polygon.technology/v0.13/wallets \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{
    "customerId": "cst_01H9Xa...",
    "type": "custodial",
    "details": { "network": "polygon", "asset": "usdc" }
  }'

{
  "id": "wlt_01H9Xb...",
  "type": "walletCrypto",
  "customer": { "id": "cst_01H9Xa..." },
  "status": "active",
  "asset": "usdc",
  "network": "polygon",
  "address": "0xbeef4a2c891d56e72b67a3f21d0cf94f1d7c5911",
  "routing": { "claimStatus": "unclaimed" },
  "provider": "...",
  "balances": [
    { "asset": "usdc", "network": "polygon", "balance": "0.000000", "estimatedValueUsd": "0.00" }
  ],
  "metadata": {},
  "createdAt": "2026-11-02T10:01:00.000Z",
  "updatedAt": "2026-11-02T10:01:00.000Z"
}

Copy the wlt_ ID. In sandbox the address lives on Polygon Amoy, the Polygon testnet.If the response is 202 instead, the wallet is still being provisioned. Poll the URL in the Location header (GET /wallets/operations/{operationId}) until its status is complete, then take the wallet ID from walletId.

Create a cash-in

Now fund the wallet with cash. First find a retail location that accepts cash deposits:

curl -G https://sandbox-api.polygon.technology/v0.13/cash-locations \
  -H "Authorization: Bearer {accessToken}" \
  -d provider={cash_provider} \
  -d flow=cash_in \
  -d latitude=37.7936 \
  -d longitude=-122.3958 \
  -d customerId=cst_01H9Xa...

Use the cash provider value enabled for your project. From the results, pick a location with buyAllowed: true and copy its id (loc_...) and cashLocationReference.Create the cash-in. The customer will deposit about $100.00, and the USDC goes to the wallet you just created:

curl -X POST https://sandbox-api.polygon.technology/v0.13/cash-ins \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{
    "customerId": "cst_01H9Xa...",
    "cash": {
      "locationId": "loc_...",
      "locationReference": "{cashLocationReference}"
    },
    "source": { "asset": "usd", "indicatedAmount": "100.00" },
    "destination": {
      "asset": "usdc",
      "network": "polygon",
      "wallet": { "id": "wlt_01H9Xb..." }
    }
  }'

{
  "id": "ci_01H9Xc...",
  "status": "pending",
  "customer": { "id": "cst_01H9Xa..." },
  "source": { "type": "cash", "asset": "usd", "details": { "locationId": "loc_..." } },
  "destination": { "type": "walletCrypto", "id": "wlt_01H9Xb...", "asset": "usdc", "network": "polygon" },
  "pricing": {
    "source": { "asset": "usd", "amount": "100.00" },
    "destination": { "asset": "usdc", "amount": "100.000000" },
    "fees": [],
    "exchangeRate": "1.0000",
    "fixedAmountSide": "source"
  },
  "depositInstructions": { "cashInCode": "483 291" },
  "expiresAt": "2026-11-02T11:02:00.000Z",
  "createdAt": "2026-11-02T10:02:00.000Z",
  "updatedAt": "2026-11-02T10:02:00.000Z"
}

The cashInCode is what a real customer would show at the counter before expiresAt. The pricing amounts are estimates until cash is actually deposited. Copy the ci_ ID and the cashInCode.

Simulate the cash deposit

In sandbox, two calls stand in for the customer at the counter. First, present the code:

curl -X POST https://sandbox-api.polygon.technology/v0.13/cash-ins/ci_01H9Xc.../simulate/present-code \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{ "cashInCode": "483 291", "amount": "100.00" }'

The response carries a confirmationId. Pass it to hand over the cash:

curl -X POST https://sandbox-api.polygon.technology/v0.13/cash-ins/ci_01H9Xc.../simulate/deposit-cash \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{
    "cashInCode": "483 291",
    "amount": "100.00",
    "originalConfirmationId": "{confirmationId}"
  }'

OMS now treats the cash as received and creates a transaction that converts it to USDC and delivers it to the wallet.

Watch the transaction complete

Read the cash-in again:

curl https://sandbox-api.polygon.technology/v0.13/cash-ins/ci_01H9Xc... \
  -H "Authorization: Bearer {accessToken}"

Notice that it now has a transactionId (txn_...) and a status of processing or completed. Read that transaction:

curl https://sandbox-api.polygon.technology/v0.13/transactions/txn_01H9Xd... \
  -H "Authorization: Bearer {accessToken}"

The transaction’s precursor is { "type": "cashIn", "id": "ci_01H9Xc..." }. Its status moves from processing to completed, and subStatus shows the step it is on, such as processing.initiated or completed.settled. Repeat the read every few seconds until it reaches completed.Finally, read the wallet with GET /wallets/wlt_01H9Xb.... The balances entry for usdc now shows the deposit.You have authenticated, onboarded a customer, provisioned a wallet, and completed a cash-to-crypto transaction.

Receive webhooks instead of polling

Polling works for a first run. In your application, let OMS tell you when things change. Register a public HTTPS endpoint:

curl -X POST https://sandbox-api.polygon.technology/v0.13/webhooks \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/oms",
    "subscriptions": ["*"]
  }'

The response contains webhook and a signingKey. Store the signingKey now. Later reads do not return it. ["*"] subscribes to every event. Run another cash-in and your endpoint receives events such as these:

Event	Fires when
`cashIn.statusChanged`	The cash-in moves, for example from `pending` to `processing` or `completed`
`transaction.created`	OMS creates the transaction for the deposit
`transaction.statusChanged`	The transaction’s `status` or `subStatus` changes
`transfer.statusChanged`	One movement of money within the transaction, such as the on-chain delivery, changes status

Each event’s data.resource is the full resource as a GET returns it, so you rarely need to read it again. Before acting on an event, verify its Webhook-Signature header (t=<timestamp>,v1=<signature>): compute HMAC-SHA256 with your signingKey over <t>.<raw body>, compare in constant time, and reject events whose timestamp is more than five minutes old. See Receiving webhooks for a full handler and Webhook events for the catalog.

Overview

Introduction

Fundamentals

Request OMS access

What’s next

Crypto to fiat

Cash-in

Fiat to crypto

API reference