Custodial wallet quickstart - Polygon Developer Docs

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.

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 {accessToken} on every other call.

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

curl -X POST https://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-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. If POST /auth/token returns 429, the endpoint is rate-limited: back off before retrying.

Create a customer

Every custodial wallet belongs to a customer. Create an individual with the identifying details OMS needs to clear them for custody:

curl -X POST https://sandbox-api.polygon.technology/v0.13/customers \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cst-wallet-quickstart-001" \
  -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}" }
    ]
  }'

curl -X POST https://api.polygon.technology/v0.13/customers \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cst-wallet-quickstart-001" \
  -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",
  "status": "active",
  "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"
}

Store the cst_ ID. birthDate, residentialAddress, and identifyingInformation are write-only, so they never appear in responses. A custodial wallet needs an active cryptoCustody endorsement; if the customer’s status is still pending, wait for it to become active (poll GET /customers/{customerId} or listen for customer.* webhooks). A 202 response means onboarding is still running: resend the identical request with the same Idempotency-Key until you get 201.

Projects that require identity verification 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. Don’t send endorsements or metadata on create; the API rejects them today. Sandbox runs the same checks as production, so use well-formed synthetic data and avoid the word “test” in names and emails. If the request fails with 400, the cause field names the field that failed; quote the Request-Id response header if you contact support.

Create a custodial wallet

Create the wallet with POST /wallets. Set type to custodial and name the asset and network in details. OMS derives the onchain address and manages the keys.

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

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

{
  "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" }
  ],
  "createdAt": "2026-11-02T10:01:00.000Z",
  "updatedAt": "2026-11-02T10:01:00.000Z"
}

The wlt_ ID is what you reference as a source or destination in quotes and transactions. In sandbox the address is on Polygon Amoy, the Polygon testnet. If the response is 202 instead of 201, the wallet is still being provisioned: poll the URL in the Location header (GET /wallets/operations/{operationId}) until its status is complete, then read the wallet by the operation’s walletId.

Read the wallet balance

GET /wallets/{id} returns the wallet with its current balances.

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

curl https://api.polygon.technology/v0.13/wallets/wlt_01H9Xb... \
  -H "Authorization: Bearer {accessToken}"

Each entry in balances carries the asset, network, balance as a decimal string at the asset’s precision, and a USD estimate in estimatedValueUsd. A new wallet starts at zero. Fund it with a fiat-to-crypto flow, then read the wallet again or subscribe to customerWallet.* and transaction.* webhooks to track the balance. To list a customer’s wallets, call GET /wallets?customerId=cst_01H9Xa....

What’s next

Custodial wallets reference

The wallet object, statuses, errors, claimed wallets, and webhook events.

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.

​What’s next

Custodial wallets reference

Fund a wallet

Get started with OMS

What’s next