Skip to content

API reference

Top-ups

Add funds by card, crypto or wire.

13 operationsBase URL https://packetexchange.io/api/v1Postman collection
BrowseTop-ups

List your top-ups

GET/api/v1/topups

Access
API key. Full-access keys only; not reachable by scoped keys.
Rate limit
100 requests per second (the default)

Your 50 most recent top-ups of every method and status.

Response 200

  • datarequired

    object[]

  • idrequired

    string (uuid) · data[].id

  • methodrequired

    string · data[].method

    stripe = cardOne of crypto, wire, stripe, x402

  • amountUsdrequired

    money · data[].amountUsd

    USD as a decimal string with exactly 6 places, e.g. "0.012500".

  • statusrequired

    string · data[].status

    One of pending, confirmed, rejected

  • cryptoTokenrequired

    string | null · data[].cryptoToken

  • cryptoNetworkrequired

    string | null · data[].cryptoNetwork

  • cryptoTxHashrequired

    string | null · data[].cryptoTxHash

  • wireReferencerequired

    string | null · data[].wireReference

  • depositAddressrequired

    string | null · data[].depositAddress

  • depositMemorequired

    string | null · data[].depositMemo

  • createdAtrequired

    string (date-time) · data[].createdAt

    ISO-8601 timestamp (UTC)

  • confirmedAtrequired

    string (date-time) | null · data[].confirmedAt

    ISO-8601 timestamp (UTC)

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Start a card top-up

POST/api/v1/topups/stripe

Access
API key. Scoped keys need billing:write.
Rate limit
100 requests per second (the default)
Safe retries
Send X-Idempotency-Key; a replay within 24 hours returns the first response.
Moves money
Starts a payment to top up your balance.

Creates a pending top-up and a card payment to confirm client-side with clientSecret and publishableKey. The balance is credited when the card processor confirms the payment. If card payments are not enabled, the pending top-up is returned with a message instead. Requires identity verification when the platform enforces it (403 KYC_REQUIRED), and is subject to account flags and top-up velocity limits.

Parameters

  • X-Idempotency-Key

    header · string

    Any unique string (a UUID is ideal). Replays within 24 hours return the first response instead of acting twice.

Request body (application/json)

  • amountUsdrequired

    number

    5 to 10000

Response 201

  • datarequired

    object

  • topupIdrequired

    string (uuid) · data.topupId

  • amountUsdrequired

    number · data.amountUsd

    Echo of the requested amount (JSON number)

  • methodrequired

    string · data.method

    One of stripe

  • statusrequired

    string · data.status

    One of pending

  • clientSecret

    string · data.clientSecret

  • publishableKey

    string | null · data.publishableKey

  • message

    string · data.message

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 409CONFLICT (or a code-specific 409): the change clashes with existing state.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
  • AlsoKYC_REQUIRED, STRIPE_ERROR

Top up with an x402 USDC payment

POST/api/v1/topups/x402

Access
API key. Scoped keys need billing:write.
Rate limit
100 requests per second (the default)
Moves money
Starts a payment to top up your balance.

Pay-per-request top-up using the x402 protocol. Call once without an X-PAYMENT header to receive a 402 challenge with the payment requirements; retry with a signed X-PAYMENT header to settle and be credited in the same request. A replayed payment returns the original top-up with already: true. It settles real USDC on Base mainnet into your live balance, so test keys are refused with 403 TEST_KEY_NOT_ALLOWED. Requires identity verification when the platform enforces it (403 KYC_REQUIRED), and is subject to account flags and top-up velocity limits.

Request body (application/json)

  • amountUsdrequired

    number

    5 to 50000

Response 200

  • datarequired

    object

  • topupIdrequired

    string (uuid) · data.topupId

  • amountUsdrequired

    number · data.amountUsd

  • methodrequired

    string · data.method

    One of x402

  • statusrequired

    string · data.status

    One of pending, confirmed

  • network

    string · data.network

  • txHash

    string · data.txHash

  • payer

    string · data.payer

  • newBalance

    number · data.newBalance

    Balance after crediting (JSON number)

  • already

    boolean · data.already

  • message

    string · data.message

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 409CONFLICT (or a code-specific 409): the change clashes with existing state.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
  • AlsoKYC_REQUIRED, TEST_KEY_NOT_ALLOWED

Start a crypto top-up

POST/api/v1/topups/crypto

Access
API key. Scoped keys need billing:write.
Rate limit
10 requests per minute
Safe retries
Send X-Idempotency-Key; a replay within 24 hours returns the first response.
Moves money
Starts a payment to top up your balance.

Returns where to send funds. When a unique deposit address (or memo) could be allocated, autoCredit is true and the deposit credits automatically on confirmation; otherwise send to the shared address quoting reference and it is credited after manual verification. A memo, when present, is mandatory. Requires identity verification when the platform enforces it (403 KYC_REQUIRED), and is subject to account flags and top-up velocity limits.

Parameters

  • X-Idempotency-Key

    header · string

    Any unique string (a UUID is ideal). Replays within 24 hours return the first response instead of acting twice.

Request body (application/json)

  • amountUsdrequired

    number

    5 to 50000

  • tokenrequired

    string

    One of BTC, ETH, USDT, USDC, SOL

  • networkrequired

    string

    One of bitcoin, ethereum, solana, tron, polygon

Response 201

  • datarequired

    object

  • topupIdrequired

    string (uuid) · data.topupId

  • amountUsdrequired

    number · data.amountUsd

  • tokenrequired

    string · data.token

    One of BTC, ETH, USDT, USDC, SOL

  • networkrequired

    string · data.network

    One of bitcoin, ethereum, solana, tron, polygon

  • depositAddressrequired

    string · data.depositAddress

  • memorequired

    string | null · data.memo

  • referencerequired

    string · data.reference

  • autoCreditrequired

    boolean · data.autoCredit

  • statusrequired

    string · data.status

    One of pending

  • messagerequired

    string · data.message

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 409CONFLICT (or a code-specific 409): the change clashes with existing state.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
  • AlsoKYC_REQUIRED

Start a wire-transfer top-up

POST/api/v1/topups/wire

Access
API key. Scoped keys need billing:write.
Rate limit
100 requests per second (the default)
Safe retries
Send X-Idempotency-Key; a replay within 24 hours returns the first response.
Moves money
Starts a payment to top up your balance.

Returns bank details and a reference you must quote on the transfer. Credited within 1-3 business days of receipt. 503 WIRE_UNAVAILABLE when wire is not offered. Requires identity verification when the platform enforces it (403 KYC_REQUIRED), and is subject to account flags and top-up velocity limits.

Parameters

  • X-Idempotency-Key

    header · string

    Any unique string (a UUID is ideal). Replays within 24 hours return the first response instead of acting twice.

Request body (application/json)

  • amountUsdrequired

    number

    100 to 100000

Response 201

  • datarequired

    object

  • topupIdrequired

    string (uuid) · data.topupId

  • amountUsdrequired

    number · data.amountUsd

  • wireReferencerequired

    string · data.wireReference

  • bankDetailsrequired

    object · data.bankDetails

  • bankNamerequired

    string · data.bankDetails.bankName

  • accountNamerequired

    string · data.bankDetails.accountName

  • ibanrequired

    string · data.bankDetails.iban

  • swiftrequired

    string · data.bankDetails.swift

  • currencyrequired

    string · data.bankDetails.currency

    One of USD

  • statusrequired

    string · data.status

    One of pending

  • messagerequired

    string · data.message

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 409CONFLICT (or a code-specific 409): the change clashes with existing state.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
  • AlsoKYC_REQUIRED, WIRE_UNAVAILABLE

List available top-up methods and their limits

GET/api/v1/topups/methods

Access
API key. Full-access keys only; not reachable by scoped keys.
Rate limit
100 requests per second (the default)

Response 200

  • datarequired

    object

  • striperequired

    object · data.stripe

  • enabledrequired

    boolean · data.stripe.enabled

  • minAmountrequired

    number · data.stripe.minAmount

  • maxAmountrequired

    number · data.stripe.maxAmount

  • currencyrequired

    string · data.stripe.currency

  • processingTimerequired

    string · data.stripe.processingTime

  • cryptorequired

    object · data.crypto

  • enabledrequired

    boolean · data.crypto.enabled

  • minAmountrequired

    number · data.crypto.minAmount

  • maxAmountrequired

    number · data.crypto.maxAmount

  • tokensrequired

    string[] · data.crypto.tokens

  • networksrequired

    string[] · data.crypto.networks

  • processingTimerequired

    string · data.crypto.processingTime

  • wirerequired

    object · data.wire

  • enabledrequired

    boolean · data.wire.enabled

  • minAmountrequired

    number · data.wire.minAmount

  • maxAmountrequired

    number · data.wire.maxAmount

  • currencyrequired

    string · data.wire.currency

  • processingTimerequired

    string · data.wire.processingTime

  • bankDetailsrequired

    object | null · data.wire.bankDetails

  • bankNamerequired

    string · data.wire.bankDetails.bankName

  • accountNamerequired

    string · data.wire.bankDetails.accountName

  • ibanrequired

    string · data.wire.bankDetails.iban

  • swiftrequired

    string · data.wire.bankDetails.swift

  • currencyrequired

    string · data.wire.bankDetails.currency

    One of USD

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Start saving a card for auto-recharge

POST/api/v1/topups/setup-intent

Access
API key. Full-access keys only; not reachable by scoped keys.
Rate limit
100 requests per second (the default)
Moves money
Starts a payment to top up your balance.

Returns a client secret to collect and save a card for later unattended charges. 503 STRIPE_DISABLED when card payments are off.

Response 201

  • datarequired

    object

  • clientSecretrequired

    string | null · data.clientSecret

  • publishableKeyrequired

    string | null · data.publishableKey

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 409CONFLICT (or a code-specific 409): the change clashes with existing state.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
  • AlsoSTRIPE_DISABLED, STRIPE_ERROR

List your saved cards

GET/api/v1/topups/payment-methods

Access
API key. Full-access keys only; not reachable by scoped keys.
Rate limit
100 requests per second (the default)

Brand, last 4 and expiry only. Empty when card payments are off or no card is saved.

Response 200

  • datarequired

    object[]

  • idrequired

    string · data[].id

  • brandrequired

    string · data[].brand

  • last4required

    string · data[].last4

  • expMonthrequired

    integer | null · data[].expMonth

  • expYearrequired

    integer | null · data[].expYear

  • isDefaultrequired

    boolean · data[].isDefault

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Set your default card

POST/api/v1/topups/payment-methods/default

Access
API key. Full-access keys only; not reachable by scoped keys.
Rate limit
100 requests per second (the default)
Moves money
Starts a payment to top up your balance.

The default card is the one auto-recharge charges.

Request body (application/json)

  • paymentMethodIdrequired

    string

Response 200

  • datarequired

    object

  • defaultPaymentMethodIdrequired

    string · data.defaultPaymentMethodId

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 409CONFLICT (or a code-specific 409): the change clashes with existing state.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
  • AlsoSTRIPE_DISABLED

Remove a saved card

DELETE/api/v1/topups/payment-methods/{id}

Access
API key. Full-access keys only; not reachable by scoped keys.
Rate limit
100 requests per second (the default)
Moves money
Starts a payment to top up your balance.

Removing the default card also clears it as default, which stops auto-recharge from charging.

Parameters

  • idrequired

    path · string

Response 200

  • datarequired

    object

  • removedrequired

    string · data.removed

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 404NOT_FOUND: no such resource on your account.
  • 409CONFLICT (or a code-specific 409): the change clashes with existing state.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get your auto-recharge settings

GET/api/v1/topups/auto-recharge

Access
API key. Full-access keys only; not reachable by scoped keys.
Rate limit
100 requests per second (the default)

Response 200

  • datarequired

    object

  • enabledrequired

    boolean · data.enabled

  • thresholdrequired

    string | null · data.threshold

    USD, 2-decimal string: recharge when the balance falls below this

  • amountrequired

    string | null · data.amount

    USD, 2-decimal string: how much each recharge adds

  • dailyCaprequired

    string | null · data.dailyCap

    USD, 2-decimal string: most that auto-recharge may charge per UTC day

  • hasDefaultCardrequired

    boolean · data.hasDefaultCard

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Update your auto-recharge settings

PUT/api/v1/topups/auto-recharge

Access
API key. Full-access keys only; not reachable by scoped keys.
Rate limit
100 requests per second (the default)
Moves money
Starts a payment to top up your balance.

Send only the fields to change; null clears a value. Enabling requires a default card and both a threshold and an amount.

Request body (application/json)

  • enabled

    boolean

  • threshold

    number | null

    0 to 100000

  • amount

    number | null

    5 to 10000

  • dailyCap

    number | null

    0 to 100000

Response 200

  • datarequired

    object

    Same fields as AutoRecharge, shown earlier on this page.

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 409CONFLICT (or a code-specific 409): the change clashes with existing state.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List your pending top-ups with payment instructions

GET/api/v1/topups/pending

Access
API key. Full-access keys only; not reachable by scoped keys.
Rate limit
100 requests per second (the default)

Pending crypto and wire top-ups with the address or bank details to complete them. Pending top-ups expire after 7 days. amountUsd here is a plain JSON number.

Response 200

  • datarequired

    object[]

  • idrequired

    string (uuid) · data[].id

  • methodrequired

    string · data[].method

    One of crypto, wire, stripe, x402

  • amountUsdrequired

    number · data[].amountUsd

  • statusrequired

    string · data[].status

    One of pending

  • referencerequired

    string | null · data[].reference

  • createdAtrequired

    string (date-time) · data[].createdAt

    ISO-8601 timestamp (UTC)

  • ageHoursrequired

    integer · data[].ageHours

  • expiresInDaysrequired

    integer · data[].expiresInDays

  • token

    string | null · data[].token

  • network

    string | null · data[].network

  • depositAddress

    string | null · data[].depositAddress

  • bankDetails

    object | null · data[].bankDetails

  • bankNamerequired

    string · data[].bankDetails.bankName

  • accountNamerequired

    string · data[].bankDetails.accountName

  • ibanrequired

    string · data[].bankDetails.iban

  • swiftrequired

    string · data[].bankDetails.swift

  • currencyrequired

    string · data[].bankDetails.currency

    One of USD

  • instructionsrequired

    string · data[].instructions

Errors

  • 400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
  • 401UNAUTHORIZED: missing, invalid, expired or revoked credential.
  • 403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
  • 429RATE_LIMITED: slow down and retry after the Retry-After seconds.
  • 500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.