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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`method`requireddata[].method	string	stripe = cardOne of `crypto`, `wire`, `stripe`, `x402`
`amountUsd`requireddata[].amountUsd	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`status`requireddata[].status	string	-One of `pending`, `confirmed`, `rejected`
`cryptoToken`requireddata[].cryptoToken	string \| null	-
`cryptoNetwork`requireddata[].cryptoNetwork	string \| null	-
`cryptoTxHash`requireddata[].cryptoTxHash	string \| null	-
`wireReference`requireddata[].wireReference	string \| null	-
`depositAddress`requireddata[].depositAddress	string \| null	-
`depositMemo`requireddata[].depositMemo	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`confirmedAt`requireddata[].confirmedAt	string (date-time) \| null	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

Name	In	Type	Description
`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)

Field	Type	Description
`amountUsd`required	number	-5 to 10000

Response 201

Field	Type	Description
`data`required	object	-
`topupId`requireddata.topupId	string (uuid)	-
`amountUsd`requireddata.amountUsd	number	Echo of the requested amount (JSON number)
`method`requireddata.method	string	-One of `stripe`
`status`requireddata.status	string	-One of `pending`
`clientSecret`data.clientSecret	string	-
`publishableKey`data.publishableKey	string \| null	-
`message`data.message	string	-

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/topups/stripe" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amountUsd": 5
}'

Run it here with a test key.

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)

Field	Type	Description
`amountUsd`required	number	-5 to 50000

Response 200

Field	Type	Description
`data`required	object	-
`topupId`requireddata.topupId	string (uuid)	-
`amountUsd`requireddata.amountUsd	number	-
`method`requireddata.method	string	-One of `x402`
`status`requireddata.status	string	-One of `pending`, `confirmed`
`network`data.network	string	-
`txHash`data.txHash	string	-
`payer`data.payer	string	-
`newBalance`data.newBalance	number	Balance after crediting (JSON number)
`already`data.already	boolean	-
`message`data.message	string	-

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/topups/x402" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amountUsd": 5
}'

Run it here with a test key.

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

Name	In	Type	Description
`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)

Field	Type	Description
`amountUsd`required	number	-5 to 50000
`token`required	string	-One of `BTC`, `ETH`, `USDT`, `USDC`, `SOL`
`network`required	string	-One of `bitcoin`, `ethereum`, `solana`, `tron`, `polygon`

Response 201

Field	Type	Description
`data`required	object	-
`topupId`requireddata.topupId	string (uuid)	-
`amountUsd`requireddata.amountUsd	number	-
`token`requireddata.token	string	-One of `BTC`, `ETH`, `USDT`, `USDC`, `SOL`
`network`requireddata.network	string	-One of `bitcoin`, `ethereum`, `solana`, `tron`, `polygon`
`depositAddress`requireddata.depositAddress	string	-
`memo`requireddata.memo	string \| null	-
`reference`requireddata.reference	string	-
`autoCredit`requireddata.autoCredit	boolean	-
`status`requireddata.status	string	-One of `pending`
`message`requireddata.message	string	-

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/topups/crypto" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amountUsd": 5,
  "token": "BTC",
  "network": "bitcoin"
}'

Run it here with a test key.

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

Name	In	Type	Description
`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)

Field	Type	Description
`amountUsd`required	number	-100 to 100000

Response 201

Field	Type	Description
`data`required	object	-
`topupId`requireddata.topupId	string (uuid)	-
`amountUsd`requireddata.amountUsd	number	-
`wireReference`requireddata.wireReference	string	-
`bankDetails`requireddata.bankDetails	object	-
`bankName`requireddata.bankDetails.bankName	string	-
`accountName`requireddata.bankDetails.accountName	string	-
`iban`requireddata.bankDetails.iban	string	-
`swift`requireddata.bankDetails.swift	string	-
`currency`requireddata.bankDetails.currency	string	-One of `USD`
`status`requireddata.status	string	-One of `pending`
`message`requireddata.message	string	-

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/topups/wire" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amountUsd": 100
}'

Run it here with a test key.

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

Field	Type	Description
`data`required	object	-
`stripe`requireddata.stripe	object	-
`enabled`requireddata.stripe.enabled	boolean	-
`minAmount`requireddata.stripe.minAmount	number	-
`maxAmount`requireddata.stripe.maxAmount	number	-
`currency`requireddata.stripe.currency	string	-
`processingTime`requireddata.stripe.processingTime	string	-
`crypto`requireddata.crypto	object	-
`enabled`requireddata.crypto.enabled	boolean	-
`minAmount`requireddata.crypto.minAmount	number	-
`maxAmount`requireddata.crypto.maxAmount	number	-
`tokens`requireddata.crypto.tokens	string[]	-
`networks`requireddata.crypto.networks	string[]	-
`processingTime`requireddata.crypto.processingTime	string	-
`wire`requireddata.wire	object	-
`enabled`requireddata.wire.enabled	boolean	-
`minAmount`requireddata.wire.minAmount	number	-
`maxAmount`requireddata.wire.maxAmount	number	-
`currency`requireddata.wire.currency	string	-
`processingTime`requireddata.wire.processingTime	string	-
`bankDetails`requireddata.wire.bankDetails	object \| null	-
`bankName`requireddata.wire.bankDetails.bankName	string	-
`accountName`requireddata.wire.bankDetails.accountName	string	-
`iban`requireddata.wire.bankDetails.iban	string	-
`swift`requireddata.wire.bankDetails.swift	string	-
`currency`requireddata.wire.bankDetails.currency	string	-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

Field	Type	Description
`data`required	object	-
`clientSecret`requireddata.clientSecret	string \| null	-
`publishableKey`requireddata.publishableKey	string \| null	-

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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string	-
`brand`requireddata[].brand	string	-
`last4`requireddata[].last4	string	-
`expMonth`requireddata[].expMonth	integer \| null	-
`expYear`requireddata[].expYear	integer \| null	-
`isDefault`requireddata[].isDefault	boolean	-

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)

Field	Type	Description
`paymentMethodId`required	string	-

Response 200

Field	Type	Description
`data`required	object	-
`defaultPaymentMethodId`requireddata.defaultPaymentMethodId	string	-

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/topups/payment-methods/default" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "paymentMethodId": "<paymentMethodId>"
}'

Run it here with a test key.

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`removed`requireddata.removed	string	-

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

Field	Type	Description
`data`required	object	-
`enabled`requireddata.enabled	boolean	-
`threshold`requireddata.threshold	string \| null	USD, 2-decimal string: recharge when the balance falls below this
`amount`requireddata.amount	string \| null	USD, 2-decimal string: how much each recharge adds
`dailyCap`requireddata.dailyCap	string \| null	USD, 2-decimal string: most that auto-recharge may charge per UTC day
`hasDefaultCard`requireddata.hasDefaultCard	boolean	-

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)

Field	Type	Description
`enabled`	boolean	-
`threshold`	number \| null	-0 to 100000
`amount`	number \| null	-5 to 10000
`dailyCap`	number \| null	-0 to 100000

Response 200

Field	Type	Description
`data`required	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.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/topups/auto-recharge" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "threshold": 1
}'

Run it here with a test key.

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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`method`requireddata[].method	string	-One of `crypto`, `wire`, `stripe`, `x402`
`amountUsd`requireddata[].amountUsd	number	-
`status`requireddata[].status	string	-One of `pending`
`reference`requireddata[].reference	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`ageHours`requireddata[].ageHours	integer	-
`expiresInDays`requireddata[].expiresInDays	integer	-
`token`data[].token	string \| null	-
`network`data[].network	string \| null	-
`depositAddress`data[].depositAddress	string \| null	-
`bankDetails`data[].bankDetails	object \| null	-
`bankName`requireddata[].bankDetails.bankName	string	-
`accountName`requireddata[].bankDetails.accountName	string	-
`iban`requireddata[].bankDetails.iban	string	-
`swift`requireddata[].bankDetails.swift	string	-
`currency`requireddata[].bankDetails.currency	string	-One of `USD`
`instructions`requireddata[].instructions	string	-

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.