API reference

Base URLs

Network	Base URL
Mainnet	`https://api.pesapay.xyz`
Testnet	`https://api-testnet.pesapay.xyz`

Conventions

JSON in and out. Send content-type: application/json with a body.
Amounts are decimal integer strings in the asset’s base units: 6 decimals for USDC and USDT0 on EVM chains, 7 decimals for Stellar assets. "20000000" on Base is 20 USDC; "200000000" on Stellar is 20 USDC.
Chains are CAIP-2 (eip155:8453, stellar:pubnet, stellar:testnet). Assets are CAIP-19 on EVM chains and stellar:CODE:ISSUER on Stellar.
EVM addresses are stored lower-case.
Times are ISO 8601 strings in UTC.
Status words follow SEP-24 and quote fields follow SEP-38.

Authentication

Send Authorization: Bearer <token>, where the token is a SEP-10 JWT or a Privy access token. GET /v1/routes, the SEP-10 endpoints and the order book need none. See Authentication.

Idempotency

POST /v1/transfers requires an Idempotency-Key header. A repeat with the same key returns the same transfer. Use a new UUID for each transfer the user starts.

Errors

Errors have a JSON body with a message.

Status	Meaning
`400`	The request is malformed: a missing field, a bad address, a bad cursor
`401`	No token, or the token is invalid or expired
`403`	The token’s owner may not do this, for example a deposit to another account
`404`	No such transfer for this owner
`409`	The request conflicts with the current state: a used or expired quote, a cancel after something irreversible, a duplicate submission
`422`	The request is valid but refused: over the daily or outstanding limit, a submission that does not match the issued action, or a transaction that is not mined yet
`503`	The route’s chain is temporarily unavailable

Limits

Limit	Value
Per transfer	$20
Started per owner per day, all routes	$100
Outstanding per owner, all routes	$100

​Base URLs

​Conventions

​Authentication

​Idempotency

​Errors

​Limits