Quickstart (using CLI)

Overview

Send a cross-rail payment using the Payment Gateway CLI. The CLI wraps the same prepare → sign → submit flow you would use with the SDK.

This guide walks through one example corridor — USDC on Arbitrum Sepolia → USDC on Celo Sepolia. Atum supports many source and destination combinations across Arbitrum, Base, Solana, Tron, and more. See Supported networks for the full list.

Approve token spend

One-time setup for your wallet on the source chain — not before every payment.

Run send-payment

The CLI builds, signs, and submits your payment in one command.

Settlement operators quote your payment

Settlement operators compete to fulfill your payment — no action needed from you.

Funds move across both rails

Settlement completes. Poll /status to confirm.

New to tokenized currency payments? Read Atum infrastructure first — about five minutes.

You do not need to run any Atum backend services, only the hosted testnet gateway and your wallet. For SDK integration in your own app, see SDK quickstart.

Prerequisites

The following is required to use Atum to send a payment:

Node.js 20+ and npm

brew install node

Verify (npm is included with Node.js):

node -v   # v20.x.x or newer
npm -v

Access to Atum's Payment Gateway

Confirm you can reach the hosted testnet API from your machine:

curl -sS https://payment-gw.production-testnet.atum.xyz/v1/defaults | python3 -m json.tool

A successful check returns HTTP 200 and one entry per chain the gateway serves, keyed by CAIP-2 id:

{
  "eip155:421614": {
    "chain_id": "eip155:421614",
    "quote_selector": "0xd0f080E23F95571D26eEb1FAD24a5F3d66835195",
    "escrow_contract": "0x0F875601504C9179562506AFa34b2D084268869b",
    "fulfillment_proxy": "0x1F1F8FA642bc5F530ba37F1Db3a656E9eB8BaFeb",
    "fulfillment_verifier": {
      "account": "0x27050EE47befC43F4dF7807a7AA8073039e5fa89",
      "endpoint": "https://veri-fill.production-testnet.atum.xyz"
    }
  },
  "eip155:11142220": { "chain_id": "eip155:11142220", "…": "…" }
}

This tells you two things at once: the gateway is up, and which chains are enabled — not which source→destination pairs you can use. A chain that isn’t fully configured is left out of this listing, so what comes back is what you can actually pay on. Fetch these addresses rather than hardcoding them; they change when a chain’s contracts are redeployed. A non-200 is a gateway-side answer, not a network problem: 404 means it resolved no chains and 503 means a dependency is down — in both cases the gateway is up and you have nothing to fix locally.The Payment Gateway is an HTTP API, not a blockchain network.

A funded testnet wallet

This example uses an EVM wallet funded on Arbitrum Sepolia. Any EVM-compatible wallet works (MetaMask, Coinbase Wallet, Rainbow, etc.).You will need:

Testnet ETH for the one-time token approval on the source chain (settlement gas is the settlement operator’s)
A small amount of testnet USDC on the source chain

You can use the same 0x address for sender and receiver. See Testnet wallet setup if you need help getting funded.

1. Install the CLI

npm install -g @atumlabs/payment-gateway-client
send-payment --help

This installs five commands: send-payment, payment-status, request-quote, quote-status and approve-permit2. Skip the -g and use npx send-payment … if you would rather not install globally.

2. Configure addresses and key

Create .env in the directory you’ll run the commands from. You will need your wallet’s private key and address (in this example, we use the same address for sender and receiver): Example (replace with your own values):

PRIVATE_KEY=0xYOUR_PRIVATE_KEY
SENDER=0xYOUR_SENDER_ADDRESS
RECEIVER=0xYOUR_RECEIVER_ADDRESS

Using a MetaMask wallet?

Your MetaMask address and private key belong to the account, not to a network.The network dropdown (Ethereum, Arbitrum Sepolia, etc.) only changes which chain you are viewing — not your credentials.Balances change by network; your 0x address and key do not.

Copy your address

Click the copy icon next to your default Metamask address.Paste that value into SENDER and RECEIVER in your .env

Export your private key

In MetaMask, click the three dots (⋮) next to your account name.
Click Account details.
Copy your account private key (it’s a long hex string starting with 0x).
Enter your MetaMask password and confirm.

Paste it into PRIVATE_KEY in your .env.

Add .env to .gitignore and never commit this file.

Load the variables before running scripts to avoid putting the key in shell history:

set -a && source .env && set +a

3. Approve USDC spend

This step is required for EVM and Tron source chains.

Before Atum can move funds from your wallet during settlement, you must approve spending once on the source chain. This is separate from signing each payment — do it one time per wallet and token, then send as many test payments as you like. Without this step, the gateway may accept your payment request, but on-chain settlement will fail.

Technical name: Permit2

Atum uses the standard Permit2 contract on EVM and Tron chains — the same approval pattern many DeFi apps use. Your USDC moves into the settlement vault only after you sign a payment.Details: Token approvals.

The package ships a command for this. It reads the current allowance first, so an already-approved wallet never has to produce a key to learn there was nothing to do:

set -a && source .env && set +a

approve-permit2 $SENDER eip155:421614/erc20:0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d \
  --rpc-url https://sepolia-rollup.arbitrum.io/rpc

It takes the same CAIP-19 asset string as send-payment. The private key comes from PRIVATE_KEY or an interactive prompt and is never accepted as a flag, which would put it in shell history and in the process list. Add --check to report whether an approval is needed without sending anything or needing a key at all. An approval is unlimited by default, so later payments need no further transaction. --amount bounds it instead, at the cost of renewing it as Permit2 consumes it.

This is the one command that spends gas. Everything else the CLI does builds and signs offline.If the transaction is broadcast but not confirmed before the timeout, the command exits non-zero and prints {"unconfirmed": true, "txHash": …}. That is not a revert — the approval may still land. Look that transaction up before re-running, rather than sending a second approval.

Approving by hand

You don’t have to use Atum’s command. The approval is an ordinary ERC-20 approve of the Permit2 contract — nothing Atum-specific — so any tool that can call it works.

From a block explorer or Remix

Tool	Link
Arbiscan (Write as Proxy on testnet USDC)	USDC contract → Write as Proxy
Remix	remix.ethereum.org — connect your wallet on the source chain and call `approve` on the USDC contract

Use spender 0x000000000022D473030F116dDEE9F6B43aC78BA3 (the standard Permit2 contract) and an amount in 6-decimal units (for example 1000000000 = 1000 USDC). Circle testnet USDC is a proxy — on Arbiscan use Write as Proxy, not Write Contract.

From your own script

Save as accept-permit2.ts and run it once with npx tsx accept-permit2.ts:

import { ethers } from 'ethers';

async function main() {
  const privateKey = process.env.PRIVATE_KEY;
  if (!privateKey) throw new Error('Set PRIVATE_KEY in .env');

  const wallet = new ethers.Wallet(
    privateKey,
    new ethers.JsonRpcProvider('https://sepolia-rollup.arbitrum.io/rpc'),
  );
  const usdc = new ethers.Contract(
    '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
    ['function approve(address spender, uint256 amount) returns (bool)'],
    wallet,
  );

  const tx = await usdc.approve('0x000000000022D473030F116dDEE9F6B43aC78BA3', 1_000_000_000n);
  await tx.wait();
  console.log(`Spending approval confirmed: ${tx.hash}`);
}

main().catch((err) => { console.error(err); process.exit(1); });

Three things are going on: connect to the source chain, call approve on the USDC contract, and name Permit2 as the spender allowed to pull USDC when a payment settles. No money moves — it is a permission slip, and you still sign each payment separately. 1_000_000_000n is a 1000 USDC ceiling for test runs.

For token approval details, see Token approvals.

4. Send your first payment

With USDC spend approved, you are ready to submit a payment. Run the following to load your .env file first:

set -a && source .env && set +a

Once your .env is loaded, run:

send-payment

send-payment \
  --gateway https://payment-gw.production-testnet.atum.xyz \
  --max-source-amount 10101 \
  $SENDER \
  10000 \
  eip155:421614/erc20:0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d \
  $RECEIVER \
  eip155:11142220/erc20:0x01C5C0122039549AD1493B8220cABEdD739BC44E

What's in this command?

send-payment takes positional arguments in this order: sender, amount, source asset, receiver, destination asset.

Argument	Example	Definition
`--gateway`	`https://payment-gw.production-testnet.atum.xyz`	Payment Gateway base URL. Fixed to the hosted testnet for this guide.
`--request-id`	(omitted here)	Optional. Your idempotency key — see the tip below.
`--max-source-amount`	`10101`	Required. The most that may leave your wallet, in atomic units of the source token: the amount plus the settlement operator’s charge. Quotes above it are not accepted. To size it, get a price quote first.
Sender	`$SENDER`	Depositor wallet — signs the payment and holds source funds. Set in `.env`.
Amount	`10000`	Payment size in atomic units (6 decimals for USDC). `10000` = 0.01 USDC. Change as needed — see Amount (atomic units) below.
Source asset	`eip155:421614/erc20:0x75faf1…`	Asset ID for USDC on Arbitrum Sepolia (source chain in this example).
Receiver	`$RECEIVER`	Account that receives funds on the destination chain. Can be the same `0x` as the sender.
Destination asset	`eip155:11142220/erc20:0x01C5C012…`	Asset ID for USDC on Celo Sepolia (destination chain in this example).

What are the `eip155:…` strings?

Those are asset IDs — one string that identifies an exact token on an exact chain. The CLI does not accept symbols like USDC; it needs the full ID. Different corridors use different asset IDs — copy them from Supported assets.

eip155:{chainId}/erc20:{tokenContractAddress}

Piece	Source asset (this example)	Destination asset (this example)
`eip155`	Prefix for EVM chains	Same
`421614` / `11142220`	Arbitrum Sepolia chain ID	Celo Sepolia chain ID
`erc20:0x…`	USDC on Arbitrum Sepolia	USDC on Celo Sepolia

Technical name: CAIP-19

Asset IDs follow the CAIP-19 standard. Chain prefixes use CAIP-2.Full catalog: Supported assets. Concept page: Corridors and assets.

Why are the asset IDs already filled in?

This quickstart pins one route so you can focus on the payment flow — not hunting token addresses at runtime.

GET /v1/defaults lists which chains are enabled and returns their on-chain contract addresses — not which tokens or asset IDs to use, and not “USDC on Arbitrum Sepolia.”
Token contract addresses come from Supported assets.

In production, store supported source/destination asset pairs in your own config. For other testnet routes, copy asset IDs from that catalog.

The command above omits --request-id, so send-payment generates a new random one (pmt-gw-cli-<timestamp>-<random>) every time you run it — each run is a new payment.If you re-run the exact same command to retry a submission that failed or timed out, pass the same --request-id explicitly so the gateway recognizes it as the same payment instead of charging a second one. See Idempotency.

Amount (atomic units)

The second argument to send-payment is not dollars — it is USDC in 6-decimal atomic units (smallest on-chain increment):

You send	CLI value
0.01 USDC	`10000`
0.10 USDC	`100000`
1.00 USDC	`1000000`

Use a small test amount (for example 10000) to conserve testnet USDC. If settlement fails with NO_QUOTES_RECEIVED, read decline_summary before retrying (see Why nobody quoted).

Your terminal should output two streams back-to-back:

Stream	Content
stderr	Signed `PaymentRequest` JSON (for debugging)
stdout	`PaymentResponse` JSON — copy `payment_id` from here

stderr (PaymentRequest)
stdout (PaymentResponse)

The client logs the signed request with console.error before submitting:

{
  "version": "1.3",
  "request_id": "pmt-gw-cli-1792405800412-k3x9q2a",
  "source": {
    "asset_identifier": "eip155:421614/erc20:0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
    "account": "0xYOUR_SENDER_ADDRESS"
  },
  "destination": [
    {
      "asset_identifier": "eip155:11142220/erc20:0x01C5C0122039549AD1493B8220cABEdD739BC44E",
      "account": "0xYOUR_RECEIVER_ADDRESS"
    }
  ],
  "fulfillment_amount": "10000",
  "max_source_amount": "10101",
  "quote_deadline": "2026-10-19T10:30:03.412Z",
  "fulfillment_deadline": "2026-10-19T11:30:00.412Z",
  "escrow_contract_address": "0x0F875601504C9179562506AFa34b2D084268869b",
  "fulfillment_verifier": {
    "account": "0x27050EE47befC43F4dF7807a7AA8073039e5fa89",
    "endpoint": "https://veri-fill.production-testnet.atum.xyz"
  },
  "sender_auth": {
    "message_scheme": "EVM_PERMIT2",
    "signed_messages": [
      { "message": "0x…", "message_prehash": "{\"domain\":{…},\"types\":{…},\"message\":{…}}", "signature": "0x…" }
    ]
  }
}

The CLI fills escrow_contract_address and fulfillment_verifier from /v1/defaults for the source chain. The gateway requires both on every payment request.Followed by the recovery line. Copy the request_id from here if you need to retry:

request_id: pmt-gw-cli-1792405800412-k3x9q2a  (re-run with --request-id pmt-gw-cli-1792405800412-k3x9q2a to retry this same payment)

The gateway response is printed with console.log:

{
  "payment_id": "0x...",
  "status": "pending",
  "idempotent_replay": false
}

A payment_id means the gateway accepted your signed request — not that settlement finished. idempotent_replay: false means this call just created the payment; true would mean you got back a payment an earlier retry already created — see Idempotency.

Continue to Check payment status with the payment_id from stdout. By default, the CLI does not poll after submit — send-payment waits as long as the gateway holds the submit call (see Track a payment), then prints the PaymentResponse above and exits. Pass --wait if you’d rather have the CLI poll for you: send-payment then blocks on /status itself and prints the payment JSON once the payout is mined (finalizing), the payment fails or is refunded, the refund is ready (refund_available), or --wait-seconds expires. Add --wait-seconds <n> to change the default 60-second cap — giving up does not affect the payment itself, it’s a convenience bound only. To wait until the payout is final (completed) instead, pass --wait-for completed and raise --wait-seconds: on some destination chains that takes tens of minutes. See Finality. The exit code tells the endings apart, with or without --wait, so don’t branch on “zero or not” — a wait that runs out its budget is not a failure, and 5 means paid:

Code	Meaning	What to do
`0`	Settled and final (`completed`).	Nothing.
`5`	Paid on chain (`finalizing`): your recipient has the funds, and the payout is not final yet.	Treat it as paid if a mined payout is enough for you. It normally becomes `completed`; poll `/status`, or use `--wait-for completed`.
`2`	Accepted, still settling (also `refunding`).	Re-run with the same `--request-id`, or poll `/status`.
`3`	Failed or refunded. Final.	A fresh attempt needs a new `--request-id`.
`4`	Not delivered, and the refund is ready. Your funds are still in the settlement vault.	Do not pay again. Submit `refund_signature` yourself. See Refunds.
`1`	No outcome obtained — rejected, unreachable, or bad arguments.	Treat as unknown, not “nothing happened”: recover like code `2`.

Review before you send

send-payment in one shot builds, signs and submits. You can also split it in two and read the signed request first:

# Build and sign, print the request, submit nothing.
# Widen the quote window: the 3s default closes before you can --submit a file.
send-payment --prepare-only \
  --gateway https://payment-gw.production-testnet.atum.xyz \
  --max-source-amount 10101 \
  --quote-deadline-seconds 30 \
  $SENDER \
  10000 \
  eip155:421614/erc20:0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d \
  $RECEIVER \
  eip155:11142220/erc20:0x01C5C0122039549AD1493B8220cABEdD739BC44E \
  > payment.json

# Send one that was prepared earlier:
send-payment --submit payment.json

# Or skip the file — "-" reads stdin, so the two pipe together:
send-payment --prepare-only \
  --gateway https://payment-gw.production-testnet.atum.xyz \
  --max-source-amount 10101 \
  $SENDER \
  10000 \
  eip155:421614/erc20:0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d \
  $RECEIVER \
  eip155:11142220/erc20:0x01C5C0122039549AD1493B8220cABEdD739BC44E \
  | send-payment --submit -

What --prepare-only prints is byte-for-byte what that run would have POSTed, so it can be reviewed or approved before any money moves.

Treat the file like a signed cheque, not a draft — it is a signed authorization and --submit needs no private key. Delete it once the payment is sent or abandoned.A prepared request is submittable only while its quote window is open, and the default is short (see Deadlines). Widen it with --quote-deadline-seconds if you intend to submit later, by seconds rather than minutes: settlement operators decline a window that ends after their quote would expire (QUOTE_WINDOW_TOO_LONG). See Deadlines.

--prepare-only still calls the gateway — that is where the corridor addresses come from — so it is not an offline signing mode. The exit codes above describe a submitted payment, so they don’t apply to a --prepare-only run, where 0 means the request was built and signed and no payment exists. Don’t chain a payment-conditional step off one.

The other commands

Command	What it does
`payment-status <paymentId>`	Read a payment’s current status. Same data as the `/status` endpoint in step 5.
`request-quote`	Open a quote-request batch and collect price quotes for a corridor, without committing to a payment. Takes its own `--request-id` — see Idempotency.
`quote-status <quoteRequestId>`	Read a batch and the quotes collected for it so far.
`approve-permit2`	The one-time token approval from step 3.

Every command takes --gateway, and both send-payment and request-quote take --request-id (or --request-id-prefix to change the generated one’s prefix). Run any of them with --help for the full flag list.

5. Check payment status

This CLI flow talks to the Payment Gateway directly, so you poll /status after submit. That is the right pattern here. For x402 / MPP HTTP payments, prefer re-attempting the same purchase when settlement is still running; keep /status for dashboards and out-of-band reconciliation. Copy payment_id from stdout in step 4, then poll every few seconds:

PAYMENT_ID=0x...   # paste from send-payment stdout

curl -sS "https://payment-gw.production-testnet.atum.xyz/v1/payments/${PAYMENT_ID}/status" | python3 -m json.tool

Optional — event timeline for debugging:

curl -sS "https://payment-gw.production-testnet.atum.xyz/v1/payments/${PAYMENT_ID}/timeline" | python3 -m json.tool

The /status response tells you how far settlement got. Once status is finalizing, the payout is mined and your recipient has the USDC: its transaction is in transactions.fulfillment. The payment becomes completed once the payout is final on the destination chain. On this quickstart’s route (Celo Sepolia) that takes tens of minutes; see Finality. To follow it to the end, poll every few seconds until status is completed, failed or refunded. What each status means: Payment status.

completed, failed and refunded are the only statuses that end a payment. Treat anything else as still in flight and keep polling — in particular, do not stop on a status you do not recognize, because giving up on a live payment is how a second charge happens.Any payment can pass through finalizing, and it is not terminal. If you write an exhaustive switch on the SDK’s PaymentStatus type, you need a branch for it.

A payment_id from step 4 only proves submit succeeded. This step confirms settlement.

Paid, then completed

While the payment is finalizing, look up the payout from transactions.fulfillment in a Celo Sepolia block explorer: USDC has arrived. Once the payout is final the status is completed. transactions lists the deposit on the source chain and the payout on the destination chain:

{
  "payment_id": "0x8329...c2c4",
  "status": "completed",
  "updated_at": "2026-07-06T23:38:30.785875Z",
  "transactions": {
    "deposit": {
      "transaction_hash": "0x38d3b4de1227396586f7807d3543377ed22ce4b172e9bc6be81de70713a482d5",
      "chain_id": "eip155:421614",
      "block_number": 284870238
    },
    "fulfillment": {
      "transaction_hash": "0xf6b5226c1ef6b88d5a325bcda28420b828f1d9e891401fd1c80c7fe1f3a31122",
      "chain_id": "eip155:11142220",
      "block_number": 30097104
    }
  }
}

View the source transaction on Arbiscan and the destination transaction on the relevant chain explorer.

Still settling

Delivery usually takes seconds on testnet. While status is pending, keep polling — do not resubmit the same payment under a new request_id. A finalizing payment is already paid; it is only waiting for the destination chain to make the payout final.

Failed (no route available)

If no settlement operator offers a price in time, you may see NO_QUOTES_RECEIVED. Your integration still worked — submit and signing succeeded. Read decline_summary in the status response to see why (see Why nobody quoted). An asset the gateway does not serve is refused at submit, with UNSUPPORTED_SOURCE_ASSET or UNSUPPORTED_DESTINATION_ASSET. An asset it serves but you did not mean, such as the right token on the wrong chain, passes submit and fails later, so also check your asset IDs against Supported assets. A payment that no one quoted looks like this:

{
  "payment_id": "0x...",
  "status": "failed",
  "error": {
    "code": "NO_QUOTES_RECEIVED",
    "domain": "PAYMENT_GATEWAY",
    "message": "No settlement quotes were received within the auction window. This request_id is spent, so a new attempt needs a new one."
  }
}

NO_QUOTES_RECEIVED is not a spending approval or signing error. Nobody quoted before the quote window closed. Read decline_summary in the status response to see why; see Why nobody quoted.

Troubleshooting

Symptom	Likely cause	What to do
`payment_id` on stdout	Submit succeeded	Poll `/status`
`status: finalizing` + `transactions.fulfillment`	Paid on chain, not final yet	Your recipient has the funds. Keep polling if you need `completed`
`status: completed` + both tx hashes	Payment fulfilled and final	Done
`NO_QUOTES_RECEIVED`	No settlement operator quoted in the quote window	Read `decline_summary`; see Why nobody quoted
Stuck `pending`	Settlement in progress	Keep polling. A large payment can stay `pending` longer while the settlement operator waits for the source chain; see Finality
Submit errors / no `payment_id`	Wallet setup (USDC spend approval, balance, signing)	Re-check Prerequisites and steps 2–3

Success criteria

You completed this quickstart when:

GET /v1/defaults returns chain defaults for the testnet gateway
Approve USDC spend confirmed on Arbitrum Sepolia
send-payment returns a payment_id on stdout
GET /v1/payments/{payment_id}/status returns "status": "finalizing" or "completed", with the payout in transactions.fulfillment

The first three items confirm your integration. The last item confirms settlement — a NO_QUOTES_RECEIVED on testnet does not invalidate the first three.

Next steps

Topic	Guide
SDK integration in your app	SDK quickstart
Payment Gateway API reference	Payment Gateway API
When settlement fails on testnet	Troubleshooting
Testnet chains and asset IDs	Supported networks · Supported assets
Key terms (Permit2, asset IDs, etc.)	Core concepts
Who does what in a payment	Who owns what

Overview

Start building

Payment lifecycle

Support

Reference

Quickstart (using CLI)

Overview

Prerequisites

1. Install the CLI

2. Configure addresses and key

Copy your address

Export your private key

3. Approve USDC spend

Approving by hand

4. Send your first payment

What are the `eip155:…` strings?

Why are the asset IDs already filled in?

Review before you send

The other commands

5. Check payment status

Paid, then completed

Still settling

Failed (no route available)

Troubleshooting

Success criteria

Next steps

​Overview

​Prerequisites

​1. Install the CLI

​2. Configure addresses and key

​Copy your address

​Export your private key

​3. Approve USDC spend

​Approving by hand

​4. Send your first payment

​What are the eip155:… strings?

​Why are the asset IDs already filled in?

​Review before you send

​The other commands

​5. Check payment status

​Paid, then completed

​Still settling

​Failed (no route available)

​Troubleshooting

​Success criteria

​Next steps

Overview

Prerequisites

1. Install the CLI

2. Configure addresses and key

Copy your address

Export your private key

3. Approve USDC spend

Approving by hand

4. Send your first payment

What are the `eip155:…` strings?

Why are the asset IDs already filled in?

Review before you send

The other commands

5. Check payment status

Paid, then completed

Still settling

Failed (no route available)

Troubleshooting

Success criteria

Next steps