Skip to main content
This quickstart provisions your first OMS custodial wallet through the API. You authenticate, create a customer to own the wallet, provision the wallet, and read its balance. OMS holds the keys, so there is no wallet SDK and no user signing.
Custodial wallets are in early access and require an OMS API key. Request access if you do not have one yet.
1

Get a bearer token

You do not send the API key directly on requests. Exchange the key and secret for a short-lived bearer token at POST /auth/token, then send that token as Authorization: Bearer {token} on every other call.
curl -X POST https://sandbox-api.polygon.technology/v0.9/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "{api_key}",
    "apiSecret": "{api_secret}"
  }'

{
  "accessToken": "eyJhbGc...",
  "tokenType": "bearer",
  "expiresIn": 3600,
  "expiresAt": "2024-01-15T11:00:00Z"
}
The token is valid for 60 minutes. When a request returns 401, exchange your key for a fresh token and retry.
2

Create a customer

Every custodial wallet belongs to a customer record. Create one before provisioning a wallet.
curl -X POST https://sandbox-api.polygon.technology/v0.9/customers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cst-wallet-quickstart-001" \
  -d '{}'

{
  "id": "cst_01H9Xa...",
  "object": "customer",
  "endorsements": [],
  "createdAt": "2024-01-15T10:00:00Z"
}
Store the cst_ ID. You pass it in the path when provisioning the wallet.
In sandbox, customers are auto-approved with full endorsements, so you can provision and use wallets without a KYC integration.
3

Provision a custodial wallet

Create the wallet with POST /customers/{id}/wallets. The customer ID goes in the path, and the body sets the asset and chain the wallet holds. OMS derives the onchain address and manages the keys.
curl -X POST https://sandbox-api.polygon.technology/v0.9/customers/cst_01H9Xa.../wallets \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wlt-quickstart-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 wallet’s onchain Polygon address. The wlt_ ID is what you reference as a source or destination in quotes and transactions.
4

Read the wallet balance

Check a wallet’s balance any time with GET /wallets/{id}/balance.
curl https://sandbox-api.polygon.technology/v0.9/wallets/wlt_01H9Xb.../balance \
  -H "Authorization: Bearer {token}"
A freshly provisioned wallet starts at zero. Fund it with a fiat-to-crypto flow, then poll this endpoint or listen for webhooks to track the balance.

​
What’s next

Custodial wallets overview

When to use custodial wallets and how OMS secures keys.

Create a wallet (API reference)

Full request and response reference for POST /customers/{id}/wallets.

Fund a wallet

Bring fiat into the wallet with the cash-in or virtual account flows.

Get started with OMS

The end-to-end payments walkthrough, from customer to first transaction.