--- title: "Create a native POL payment window" method: POST path: "/deposit/create" tags: ["Transactions"] --- # Create a native POL payment window `POST /deposit/create` ## Request - Base URL: `https://nano-gpt.com/api` - URL: `https://nano-gpt.com/api/deposit/create` - Auth: one of: - HTTP bearer - API key in header `x-api-key` Create an API-key-authenticated native POL top-up on Polygon PoS. amount is USD, token POL or POLYGON. The address is reused but monitoring requires a new active request for each transfer. A quote is not a locked exchange rate. Use one transfer per request and keep a wallet-side payment record to avoid sending twice. Other deposit/create network flows are outside this documented POL contract. Requests with Idempotency-Key, including replays, are limited to 30 per 10 minutes per account and tenant. Follow Retry-After and bounded backoff. ## Headers - `Idempotency-Key` string ## Request body - PolygonDepositRequest - `network` 'polygon', required - `token` 'POL' | 'POLYGON', required: Native POL on Polygon PoS (chain ID 137). POLYGON is the compatibility alias. - `amount` number, required: Requested gross USD estimate, not a number of POL. The minimum applies before conversion spread and bonus. - `expires_at` integer: Optional future Unix timestamp in seconds, at most 30 minutes from now. Omit to use the default 30-minute window. Keep unchanged on idempotent retries. ## Response `200` Payment instructions, or a replay refreshed with current status. Send only if this logical top-up has not already been paid and its window is active. - PolygonDeposit: Creation instructions or current status. Original quote fields can be absent on historical/settled records. Monetary fields labeled quoted or estimated are not settled credit. - `network` 'polygon' - `token` string: POL for current native deposits. - `chainId` 137 - `tokenDecimals` 18 - `address` string: Receiving address; create a fresh payment window before every transfer despite address reuse. - `jobId` string - `txId` string: Opaque status identifier: address:jobId:expiry. Persist exactly and URL-encode when polling. - `statusUrl` string: Relative URL to poll on https://nano-gpt.com with the same account API key. - `status` 'PENDING' | 'CONFIRMING' | 'PROCESSING' | 'COMPLETED' | 'EXPIRED' | 'FAILED' - `balanceCredited` boolean: True only when the status endpoint verifies a completed account-owned ledger deposit. Present in status responses. - `creditedUsd` number: Final credited USD when balanceCredited is true; prefer settlement.creditedUsdExact for exact accounting. - `requestedUsd` number: Original requested gross USD estimate. - `quotedTokenAmount` string: Quoted POL quantity as a decimal string, not a guaranteed final USD credit. - `quotedTokenAmountAtomic` string: Quoted POL quantity in atomic units (18 decimals). Parse as BigInt or another exact integer, never a floating-point Number. - `quotedTokenUsdPrice` number: Indicative quote price, not a locked settlement price. - `priceLocked` false - `creditEstimate` PolygonDepositCreditEstimate: Indicative USD breakdown: conversion spread, consolidation fee, then bonus. Final credit uses actual POL received and settlement pricing. Never treat this as a locked exchange rate. - `grossUsdExact` string, required: Exact decimal string. Use decimal arithmetic. - `conversionSpreadRateExact` string, required: Exact decimal string. Use decimal arithmetic. - `conversionSpreadUsdExact` string, required: Exact decimal string. Use decimal arithmetic. - `consolidationFeeUsdExact` string, required: Exact decimal string. Use decimal arithmetic. - `netBeforeBonusUsdExact` string, required: Exact decimal string. Use decimal arithmetic. - `bonusRateExact` string, required: Exact decimal string. Use decimal arithmetic. - `bonusUsdExact` string, required: Exact decimal string. Use decimal arithmetic. - `estimatedCreditedUsdExact` string, required: Exact decimal string. Use decimal arithmetic. - `basis` 'requested_usd_at_quote_price', required - `expiresAt` integer: Payment-window expiry as Unix seconds. Do not send against expired or cancelled requests. - `remainingTime` integer: Seconds remaining when this response was built. - `minimumDepositUsd` number: Minimum requested gross USD estimate. - `consolidationFeeUsd` number - `consolidationFeeUsdExact` string: Exact decimal string. Use decimal arithmetic. - `estimatedCreditUsd` number: Legacy estimate after conversion spread and consolidation fee, before bonus. - `amountCrypto` union: Ambiguous legacy field. Creation responses contain the USD estimate, NOT POL. Use quotedTokenAmount; status may use this legacy field for an observed amount. - number - string - `quotedEthAmount` string: Legacy alias for quotedTokenAmount on native POL. - `quotedEthAmountWei` string: Legacy alias for quotedTokenAmountAtomic on native POL. - `txHash` string - `paidTokenAmount` string: Exact decimal string. Use decimal arithmetic. - `paidTokenAmountAtomic` string - `settlement` object: Only returned for verified COMPLETED ledger rows. Historical bonus components are null if unavailable or inconsistent; no bonus is inferred. - `creditedUsdExact` string, required: Exact decimal string. Use decimal arithmetic. - `baseUsdExact` string, nullable, required - `bonusUsdExact` string, nullable, required - `bonusRateExact` string, nullable, required - `breakdownSource` 'cryptoBonus' | 'null', nullable, required ## Other responses - `400`: Invalid body, expiry or idempotency key. - `401`: Missing or invalid authentication. - `409`: deposit_already_pending includes the existing transaction; it can be for another requested amount. deposit_creation_in_progress or idempotency_in_progress means retry unchanged, with backoff. idempotency_key_mismatch means the same key was used with different input. Do not send a second payment. - `429`: Account creation/replay rate limit exceeded. Retain the same key and retry after Retry-After seconds. - `503`: Monitoring, creation, or replay verification is unavailable or uncertain. Preserve the same key and any returned txId; do not assume no window exists. ## Changes - **2026-11-03** `cc8b07d75689`: 1 info - endpoint added [Operation history](https://skmtc.dev/nano-gpt/apis/nanogpt-api/changes/deposit/create/post.md) --- [API](https://skmtc.dev/nano-gpt/apis/nanogpt-api.md) - [All operations](https://skmtc.dev/nano-gpt/apis/nanogpt-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nano-gpt/apis/nanogpt-api/revisions/cc8b07d75689?raw)