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. If you plan to fund the wallet with fiat (the next-step cash or card flows), include the full set of identifying fields so the customer can be provisioned to move money, not just a name.
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 '{
    "type": "individual",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+12125551234",
    "birthDate": "1990-05-15",
    "nationality": "US",
    "residentialAddress": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "zipCode": "10001"
    },
    "identifyingInformation": [
      { "type": "ssn", "issuingCountry": "US", "number": "123-45-6789" }
    ],
    "endorsements": ["basic", "cryptoCustody", "usd"]
  }'

{
  "id": "cst_01H9Xa...",
  "object": "customer",
  "endorsements": [
    { "type": "basic", "status": "PENDING" },
    { "type": "cryptoCustody", "status": "PENDING" },
    { "type": "usd", "status": "PENDING" }
  ],
  "createdAt": "2024-01-15T10:00:00Z"
}
Store the cst_ ID. You pass it in the path when provisioning the wallet.
A custodial wallet can be created for a name-only customer, but that customer cannot be provisioned to move fiat. If you later fund the wallet with a fiat-to-crypto flow, those calls fail with provider account not provisioned for this customer. For USD and cash flows, provide a structured residentialAddress, phone (E.164), birthDate, and a government ID in identifyingInformation (for US customers, an ssn or itin) at creation, or add them later with PATCH /customers/{customerId}.
In sandbox, endorsements are auto-approved so you can provision and use wallets without a live KYC integration. Provisioning still reads the identifying fields above, so include them in sandbox too.
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.